Commit 9756d1da authored by Nathaniel Waisbrot's avatar Nathaniel Waisbrot Committed by Jay Satiro
Browse files

CURLOPT_DEFAULT_PROTOCOL: added 

- Add new option CURLOPT_DEFAULT_PROTOCOL to allow specifying a default
protocol for schemeless URLs.

- Add new tool option --proto-default to expose
CURLOPT_DEFAULT_PROTOCOL.

In the case of schemeless URLs libcurl will behave in this way:

When the option is used libcurl will use the supplied default.

When the option is not used, libcurl will follow its usual plan of
guessing from the hostname and falling back to 'http'.
parent 22cb6311

docs/curl.1

+25 −0
Original line number Diff line number Diff line
@@ -1312,6 +1312,25 @@ This option can be used multiple times, in which case the effect is the same 
as concatenating the protocols into one instance of the option.



(Added in 7.20.2)

.IP "--proto-default <protocol>"

Tells curl to use \fIprotocol\fP for any URL missing a scheme name.



Example:



.RS

.IP "--proto-default https ftp.mozilla.org"

https://ftp.mozilla.org

.RE



An unknown or unsupported protocol causes error

\fICURLE_UNSUPPORTED_PROTOCOL\fP.



This option does not change the default proxy protocol (http).



Without this option curl would make a guess based on the host, see \fI--url\fP

for details.



(Added in 7.45.0)

.IP "--proto-redir <protocols>"

Tells curl to use the listed protocols on redirect. See --proto for how

protocols are represented.
@@ -1773,6 +1792,12 @@ If this option is used several times, the last one will be used. 
Specify a URL to fetch. This option is mostly handy when you want to specify

URL(s) in a config file.



If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)

then curl will make a guess based on the host. If the outermost sub-domain name

matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be used,

otherwise HTTP will be used. Since 7.45.0 guessing can be disabled by setting a

default protocol, see \fI--proto-default\fP for details.



This option may be used any number of times. To control where this URL is

written, use the \fI-o, --output\fP or the \fI-O, --remote-name\fP options.

.IP "-v, --verbose"

docs/libcurl/curl_easy_setopt.3

+2 −0
Original line number Diff line number Diff line
@@ -153,6 +153,8 @@ Disable squashing /../ and /./ sequences in the path. See \fICURLOPT_PATH_AS_IS( 
Allowed protocols. See \fICURLOPT_PROTOCOLS(3)\fP

.IP CURLOPT_REDIR_PROTOCOLS

Protocols to allow redirects to. See \fICURLOPT_REDIR_PROTOCOLS(3)\fP

.IP CURLOPT_DEFAULT_PROTOCOL

Default protocol. See \fICURLOPT_DEFAULT_PROTOCOL(3)\fP

.IP CURLOPT_PROXY

Proxy to use. See \fICURLOPT_PROXY(3)\fP

.IP CURLOPT_PROXYPORT

docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3

0 → 100644
+79 −0
Original line number Diff line number Diff line 
.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  Project                     ___| | | |  _ \| |

.\" *                             / __| | | | |_) | |

.\" *                            | (__| |_| |  _ <| |___

.\" *                             \___|\___/|_| \_\_____|

.\" *

.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" *

.\" * This software is licensed as described in the file COPYING, which

.\" * you should have received as part of this distribution. The terms

.\" * are also available at http://curl.haxx.se/docs/copyright.html.

.\" *

.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell

.\" * copies of the Software, and permit persons to whom the Software is

.\" * furnished to do so, under the terms of the COPYING file.

.\" *

.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY

.\" * KIND, either express or implied.

.\" *

.\" **************************************************************************

.\"

.TH CURLOPT_DEFAULT_PROTOCOL 3 "18 Aug 2015" "libcurl 7.45.0" "curl_easy_setopt options"

.SH NAME

CURLOPT_DEFAULT_PROTOCOL \- default protocol to use if the URL is missing a

scheme name

.SH SYNOPSIS

#include <curl/curl.h>



CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEFAULT_PROTOCOL, char

*protocol);

.SH DESCRIPTION

This option tells libcurl to use \fIprotocol\fP if the URL is missing a scheme

name.



Use one of these protocol (scheme) names:



dict, file, ftp, ftps, gopher, http, https, imap, imaps, ldap, ldaps, pop3,

pop3s, rtsp, scp, sftp, smb, smbs, smtp, smtps, telnet, tftp



An unknown or unsupported protocol causes error

\fICURLE_UNSUPPORTED_PROTOCOL\fP when libcurl parses a schemeless URL. Parsing

happens when \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP is

called. The protocols supported by libcurl will vary depending on how it was

built. Use \fIcurl_version_info(3)\fP if you need a list of protocol names

supported by the build of libcurl that you are using.



This option does not change the default proxy protocol (http).



Without this option libcurl would make a guess based on the host, see

\fICURLOPT_URL(3)\fP for details.

.SH DEFAULT

NULL (make a guess based on the host)

.SH PROTOCOLS

All

.SH EXAMPLE

.nf

curl = curl_easy_init();

if(curl) {

  /* set a URL without a scheme */

  curl_easy_setopt(curl, CURLOPT_URL, "example.com");



  /* set the default protocol (scheme) for schemeless URLs */

  curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https");



  /* Perform the request */

  curl_easy_perform(curl);

}

.fi

.SH AVAILABILITY

Added in 7.45.0

.SH RETURN VALUE

CURLE_OK if the option is supported.



CURLE_OUT_OF_MEMORY if there was insufficient heap space.



CURLE_UNKNOWN_OPTION if the option is not supported.

.SH "SEE ALSO"

.BR CURLOPT_URL "(3), "

docs/libcurl/opts/CURLOPT_URL.3

+5 −3
Original line number Diff line number Diff line
@@ -40,9 +40,11 @@ libcurl doesn't validate the syntax or use this variable until the transfer is 
issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will

still return \fICURLE_OK\fP.



If the given URL lacks the scheme (such as "http://" or "ftp://" etc) then

libcurl will attempt to resolve the protocol based on one of the following

given host names: HTTP, FTP, DICT, LDAP, IMAP, POP3 or SMTP

If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)

then libcurl will make a guess based on the host. If the outermost sub-domain

name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be

used, otherwise HTTP will be used. Since 7.45.0 guessing can be disabled by

setting a default protocol, see \fICURLOPT_DEFAULT_PROTOCOL(3)\fP for details.



Should the protocol, either that specified by the scheme or deduced by libcurl

from the host name, not be supported by libcurl then

docs/libcurl/opts/Makefile.am

+4 −3
Original line number Diff line number Diff line
@@ -115,7 +115,7 @@ man_MANS = CURLOPT_ACCEPT_ENCODING.3 CURLOPT_ACCEPTTIMEOUT_MS.3 \ 
 CURLMOPT_TIMERFUNCTION.3 CURLOPT_UNIX_SOCKET_PATH.3			\

 CURLOPT_PATH_AS_IS.3 CURLOPT_PROXY_SERVICE_NAME.3			\

 CURLOPT_SERVICE_NAME.3 CURLOPT_PIPEWAIT.3 CURLMOPT_PUSHDATA.3		\

 CURLMOPT_PUSHFUNCTION.3

 CURLMOPT_PUSHFUNCTION.3 CURLOPT_DEFAULT_PROTOCOL.3



HTMLPAGES = CURLOPT_ACCEPT_ENCODING.html CURLOPT_ACCEPTTIMEOUT_MS.html	\

 CURLOPT_ADDRESS_SCOPE.html CURLOPT_APPEND.html				\
@@ -224,7 +224,7 @@ HTMLPAGES = CURLOPT_ACCEPT_ENCODING.html CURLOPT_ACCEPTTIMEOUT_MS.html \ 
 CURLOPT_UNIX_SOCKET_PATH.html CURLOPT_PATH_AS_IS.html			\

 CURLOPT_PROXY_SERVICE_NAME.html CURLOPT_SERVICE_NAME.html		\

 CURLOPT_PIPEWAIT.html CURLMOPT_PUSHDATA.html				\

 CURLMOPT_PUSHFUNCTION.html

 CURLMOPT_PUSHFUNCTION.html CURLOPT_DEFAULT_PROTOCOL.html



PDFPAGES = CURLOPT_ACCEPT_ENCODING.pdf CURLOPT_ACCEPTTIMEOUT_MS.pdf	\

 CURLOPT_ADDRESS_SCOPE.pdf CURLOPT_APPEND.pdf CURLOPT_AUTOREFERER.pdf	\
@@ -330,7 +330,8 @@ PDFPAGES = CURLOPT_ACCEPT_ENCODING.pdf CURLOPT_ACCEPTTIMEOUT_MS.pdf \ 
 CURLMOPT_TIMERDATA.pdf CURLMOPT_TIMERFUNCTION.pdf			\

 CURLOPT_UNIX_SOCKET_PATH.pdf CURLOPT_PATH_AS_IS.pdf			\

 CURLOPT_PROXY_SERVICE_NAME.pdf CURLOPT_SERVICE_NAME.pdf		\

 CURLOPT_PIPEWAIT.pdf CURLMOPT_PUSHDATA.pdf CURLMOPT_PUSHFUNCTION.pdf

 CURLOPT_PIPEWAIT.pdf CURLMOPT_PUSHDATA.pdf CURLMOPT_PUSHFUNCTION.pdf	\

 CURLOPT_DEFAULT_PROTOCOL.pdf



CLEANFILES = $(HTMLPAGES) $(PDFPAGES)