aboutsummaryrefslogtreecommitdiff
path: root/docs/libcurl
diff options
context:
space:
mode:
authorNathaniel Waisbrot <code@waisbrot.net>2015-08-22 21:49:26 -0400
committerJay Satiro <raysatiro@yahoo.com>2015-08-22 21:57:14 -0400
commit9756d1da7637d1913b7ca2b589e4635f32ed3e00 (patch)
tree4ab19870277d1b8307233356ec59415346bd843b /docs/libcurl
parent22cb63119889f57019449c9412f69a1e07ada696 (diff)
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'.
Diffstat (limited to 'docs/libcurl')
-rw-r--r--docs/libcurl/curl_easy_setopt.32
-rw-r--r--docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.379
-rw-r--r--docs/libcurl/opts/CURLOPT_URL.38
-rw-r--r--docs/libcurl/opts/Makefile.am7
-rw-r--r--docs/libcurl/symbols-in-versions1
5 files changed, 91 insertions, 6 deletions
diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index a9a6230f2..9510825d8 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -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
diff --git a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3
new file mode 100644
index 000000000..1091d17f2
--- /dev/null
+++ b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3
@@ -0,0 +1,79 @@
+.\" **************************************************************************
+.\" * _ _ ____ _
+.\" * 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), "
diff --git a/docs/libcurl/opts/CURLOPT_URL.3 b/docs/libcurl/opts/CURLOPT_URL.3
index 6e4824a9f..83d41c10b 100644
--- a/docs/libcurl/opts/CURLOPT_URL.3
+++ b/docs/libcurl/opts/CURLOPT_URL.3
@@ -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
diff --git a/docs/libcurl/opts/Makefile.am b/docs/libcurl/opts/Makefile.am
index 4865b41b5..a33607b65 100644
--- a/docs/libcurl/opts/Makefile.am
+++ b/docs/libcurl/opts/Makefile.am
@@ -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)
diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions
index 4021c7607..82933a71a 100644
--- a/docs/libcurl/symbols-in-versions
+++ b/docs/libcurl/symbols-in-versions
@@ -339,6 +339,7 @@ CURLOPT_CRLFILE 7.19.0
CURLOPT_CUSTOMREQUEST 7.1
CURLOPT_DEBUGDATA 7.9.6
CURLOPT_DEBUGFUNCTION 7.9.6
+CURLOPT_DEFAULT_PROTOCOL 7.45.0
CURLOPT_DIRLISTONLY 7.17.0
CURLOPT_DNS_CACHE_TIMEOUT 7.9.3
CURLOPT_DNS_INTERFACE 7.33.0