diff options
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 | 57 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_INFILESIZE.3 | 58 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_PORT.3 | 51 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_PROXY.3 | 84 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 | 49 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_RANGE.3 | 54 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_TIMEOUT.3 | 57 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_URL.3 | 283 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_USERPWD.3 | 64 |
9 files changed, 757 insertions, 0 deletions
diff --git a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 new file mode 100644 index 000000000..94b858fde --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 @@ -0,0 +1,57 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2014, 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_ERRORBUFFER 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_ERRORBUFFER \- set error buffer for error messages +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ERRORBUFFER, [argument]); +.SH DESCRIPTION +Pass a char * to a buffer that the libcurl may store human readable error +messages in on failures or problems. This may be more helpful than just the +return code from \fIcurl_easy_perform(3)\fP and related functions. The buffer +\fBmust be at least CURL_ERROR_SIZE bytes big\fP. + +You must keep the associated buffer available until libcurl no longer needs +it. Failing to do so will cause very odd behavior or even crashes. libcurl +will need it until you call \fIcurl_easy_cleanup(3)\fP or you set the same +option again to use a different pointer. + +Consider \fICURLOPT_VERBOSE(3)\fP and \fICURLOPT_DEBUGFUNCTION(3)\fP to better +debug and trace why errors happen. + +If the library does not return an error, the buffer may not have been +touched. Do not rely on the contents in those cases. +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_DEBUGFUNCTION "(3), " CURLOPT_VERBOSE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE.3 b/docs/libcurl/opts/CURLOPT_INFILESIZE.3 new file mode 100644 index 000000000..129414c07 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE.3 @@ -0,0 +1,58 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2014, 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_INFILESIZE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_INFILESIZE \- set size of the input file to send off +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INFILESIZE, long filesize); +.SH DESCRIPTION +When uploading a file to a remote site, \fIfilesize\fP should be used to tell +libcurl what the expected size of the input file is. This value must be passed +as a long. See also \fICURLOPT_INFILESIZE_LARGE(3)\fP for sending files larger +than 2GB. + +For uploading using SCP, this option or \fICURLOPT_INFILESIZE_LARGE(3)\fP is +mandatory. + +To unset this value again, set it to -1. + +When sending emails using SMTP, this command can be used to specify the +optional SIZE parameter for the MAIL FROM command. + +This option does not limit how much data libcurl will actually send, as that +is controlled entirely by what the read callback returns, but telling one +value and sending a different amount may lead to errors. +.SH DEFAULT +Unset +.SH PROTOCOLS +Many +.SH EXAMPLE +TODO +.SH AVAILABILITY +SMTP support added in 7.23.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_INFILESIZE_LARGE "(3), " CURLOPT_UPLOAD "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PORT.3 b/docs/libcurl/opts/CURLOPT_PORT.3 new file mode 100644 index 000000000..5fd19c79a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PORT.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2014, 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_PORT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PORT \- set remote port number to work with +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PORT, long number); +.SH DESCRIPTION +This option sets \fInumber\fP to be the remote port number to connect to, +instead of the one specified in the URL or the default port for the used +protocol. + +Usually, you just let the URL decide which port to use but this allows the +application to override that. + +While this option accepts a 'long', a port number is usually a 16 bit number +and therefore using a port number over 65535 will cause a run-time error. +.SH DEFAULT +By default this is 0 which makes it not used. +.SH PROTOCOLS +Used for all protocols that speak to a port number. +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PROXY.3 b/docs/libcurl/opts/CURLOPT_PROXY.3 new file mode 100644 index 000000000..53cf2a999 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY.3 @@ -0,0 +1,84 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2014, 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_PROXY 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROXY \- set proxy to use +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY, char *proxy); +.SH DESCRIPTION +Set the \fIproxy\fP to use for the upcoming request. The parameter should be a +char * to a zero terminated string holding the host name or dotted IP +address. + +To specify port number in this string, append :[port] to the end of the host +name. The proxy's port number may optionally be specified with the separate +option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl will default to +using port 1080 for proxies. + +The proxy string may be prefixed with [scheme]:// to specify which kind of +proxy is used. Use socks4://, socks4a://, socks5:// or socks5h:// (the last +one to enable socks5 and asking the proxy to do the resolving, also known as +\fICURLPROXY_SOCKS5_HOSTNAME\fP type) to request the specific SOCKS version to +be used. No protocol specified, http:// and all others will be treated as HTTP +proxies. + +Without a scheme prefix, \fICURLOPT_PROXYTYPE(3)\fP can be used to specify +which kind of proxy the string identifies. + +When you tell the library to use a HTTP proxy, libcurl will transparently +convert operations to HTTP even if you specify an FTP URL etc. This may have +an impact on what other features of the library you can use, such as +\fICURLOPT_QUOTE(3)\fP and similar FTP specifics that don't work unless you +tunnel through the HTTP proxy. Such tunneling is activated with +\fICURLOPT_HTTPPROXYTUNNEL(3)\fP. + +libcurl respects the environment variables \fBhttp_proxy\fP, \fBftp_proxy\fP, +\fBall_proxy\fP etc, if any of those are set. The \fICURLOPT_PROXY(3)\fP +option does however override any possibly set environment variables. + +Setting the proxy string to "" (an empty string) will explicitly disable the +use of a proxy, even if there is an environment variable set for it. + +A proxy host string given in an environment variable can also include protocol +scheme (http://) and embedded user + password. +.SH DEFAULT +Default is NULL, meaning no proxy is used. + +When you set a host name to use, do not assume that there's any particular +single port number used widely for proxies. Specify it! +.SH PROTOCOLS +All except file://. Note that some protocols don't do very well over proxy. +.SH EXAMPLE +TODO +.SH AVAILABILITY +Since 7.14.1 the proxy environment variable names can include the protocol +scheme. + +Since 7.21.7 the proxy string supports the socks protocols as "schemes". +.SH RETURN VALUE +Returns CURLE_OK. +.SH "SEE ALSO" +.BR CURLOPT_PROXYPORT "(3), " CURLOPT_HTTPPROXYTUNNEL "(3), " +.BR CURLOPT_PROXYTYPE "(3)" diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 new file mode 100644 index 000000000..3f50dbdec --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 @@ -0,0 +1,49 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2014, 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_PROXYUSERPWD 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROXYUSERPWD \- set user and password to use for the proxy +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERPWD, char *userpwd); +.SH DESCRIPTION +Pass a char * as parameter, which should be [user name]:[password] to use for +the connection to the HTTP proxy. Both the name and the password will be URL +decoded before use, so to include for example a colon in the user name you +should encode it as %3A. (This is different to how \fICURLOPT_USERPWD(3)\fP is +used - beware.) + +Use \fICURLOPT_PROXYAUTH(3)\fP to specify the authentication method. +.SH DEFAULT +This is NULL by default. +.SH PROTOCOLS +Used with all protocols that can use a proxy +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RANGE.3 b/docs/libcurl/opts/CURLOPT_RANGE.3 new file mode 100644 index 000000000..88c02bd1f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RANGE.3 @@ -0,0 +1,54 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2014, 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_RANGE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_RANGE \- set byte range to request +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RANGE, char *range); +.SH DESCRIPTION +Pass a char * as parameter, which should contain the specified range you want +to retrieve. It should be in the format "X-Y", where either X or Y may be left +out and X and Y are byte indexes. + +HTTP transfers also support several intervals, separated with commas as in +\fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP +server to send the response document in pieces (using standard MIME separation +techniques). For RTSP, the formatting of a range should follow RFC2326 Section +12.29. For RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges should +be given in npt, utc, or smpte formats. + +Pass a NULL to this option to disable the use of ranges. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP, FTP, FILE and RTSP +.SH EXAMPLE +TODO +.SH AVAILABILITY +FILE since 7.18.0, RTSP since 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_RESUME_FROM "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_TIMEOUT.3 new file mode 100644 index 000000000..7d92d3962 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT.3 @@ -0,0 +1,57 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2014, 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_TIMEOUT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TIMEOUT \- set maximum time the request is allowed to take +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT, long timeout); +.SH DESCRIPTION +Pass a long as parameter containing \fItimeout\fP - the maximum time in +seconds that you allow the libcurl transfer operation to take. Normally, name +lookups can take a considerable time and limiting operations to less than a +few minutes risk aborting perfectly normal operations. This option may cause +libcurl to use the SIGALRM signal to timeout system calls. + +In unix-like systems, this might cause signals to be used unless +\fICURLOPT_NOSIGNAL(3)\fP is set. + +Since this puts a hard limit for how long time a request is allowed to take, +it has limited use in dynamic use cases with varying transfer times. You are +then adviced to explore \fICURLOPT_LOW_SPEED_LIMIT(3)\fP, +\fICURLOPT_LOW_SPEED_TIME(3)\fP or using \fICURLOPT_PROGRESSFUNCTION(3)\fP to +implement your own timeout logic. +.SH DEFAULT +Default timeout is 0 (zero) which means it never times out during transfer. +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_TIMEOUT_MS "(3), " +.BR CURLOPT_CONNECTTIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_URL.3 b/docs/libcurl/opts/CURLOPT_URL.3 new file mode 100644 index 000000000..e389b7f3c --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_URL.3 @@ -0,0 +1,283 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2014, 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_URL 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_URL \- provide the URL to use in the reqest +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL); +.SH DESCRIPTION +Pass in a pointer to the \fIURL\fP to work with. The parameter should be a +char * to a zero terminated string which must be URL-encoded in the following +format: + +scheme://host:port/path + +For a greater explanation of the format please see RFC3986. + +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 + +Should the protocol, either that specified by the scheme or deduced by libcurl +from the host name, not be supported by libcurl then +\fICURLE_UNSUPPORTED_PROTOCOL\fP will be returned from either the +\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP functions when you +call them. Use \fIcurl_version_info(3)\fP for detailed information of which +protocols are supported by the build of libcurl you are using. + +The host part of the URL contains the address of the server that you want to +connect to. This can be the fully qualified domain name of the server, the +local network name of the machine on your network or the IP address of the +server or machine represented by either an IPv4 or IPv6 address. For example: + +http://www.example.com/ + +http://hostname/ + +http://192.168.0.1/ + +http://[2001:1890:1112:1::20]/ + +It is also possible to specify the user name, password and any supported login +options as part of the host, for the following protocols, when connecting to +servers that require authentication: + +http://user:password@www.example.com + +ftp://user:password@ftp.example.com + +imap://user:password;options@mail.example.com + +pop3://user:password;options@mail.example.com + +smtp://user:password;options@mail.example.com + +At present only IMAP, POP3 and SMTP support login options as part of the host. +For more information about the login options in URL syntax please see RFC2384, +RFC5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in 7.31.0). + +The port is optional and when not specified libcurl will use the default port +based on the determined or specified protocol: 80 for HTTP, 21 for FTP and 25 +for SMTP, etc. The following examples show how to specify the port: + +http://www.example.com:8080/ - This will connect to a web server using port +8080 rather than 80. + +smtp://mail.example.com:587/ - This will connect to a SMTP server on the +alternative mail port. + +The path part of the URL is protocol specific and whilst some examples are +given below this list is not conclusive: + +.IP HTTP +The path part of a HTTP request specifies the file to retrieve and from what +directory. If the directory is not specified then the web server's root +directory is used. If the file is omitted then the default document will be +retrieved for either the directory specified or the root directory. The exact +resource returned for each URL is entirely dependent on the server's +configuration. + +http://www.example.com - This gets the main page from the web server. + +http://www.example.com/index.html - This returns the main page by explicitly +requesting it. + +http://www.example.com/contactus/ - This returns the default document from +the contactus directory. + +.IP FTP +The path part of an FTP request specifies the file to retrieve and from what +directory. If the file part is omitted then libcurl downloads the directory +listing for the directory specified. If the directory is omitted then +the directory listing for the root / home directory will be returned. + +ftp://ftp.example.com - This retrieves the directory listing for the root +directory. + +ftp://ftp.example.com/readme.txt - This downloads the file readme.txt from the +root directory. + +ftp://ftp.example.com/libcurl/readme.txt - This downloads readme.txt from the +libcurl directory. + +ftp://user:password@ftp.example.com/readme.txt - This retrieves the readme.txt +file from the user's home directory. When a username and password is +specified, everything that is specified in the path part is relative to the +user's home directory. To retrieve files from the root directory or a +directory underneath the root directory then the absolute path must be +specified by prepending an additional forward slash to the beginning of the +path. + +ftp://user:password@ftp.example.com//readme.txt - This retrieves the readme.txt +from the root directory when logging in as a specified user. + +.IP SMTP +The path part of a SMTP request specifies the host name to present during +communication with the mail server. If the path is omitted then libcurl will +attempt to resolve the local computer's host name. However, this may not +return the fully qualified domain name that is required by some mail servers +and specifying this path allows you to set an alternative name, such as +your machine's fully qualified domain name, which you might have obtained +from an external function such as gethostname or getaddrinfo. + +smtp://mail.example.com - This connects to the mail server at example.com and +sends your local computer's host name in the HELO / EHLO command. + +smtp://mail.example.com/client.example.com - This will send client.example.com in +the HELO / EHLO command to the mail server at example.com. + +.IP POP3 +The path part of a POP3 request specifies the message ID to retrieve. If the +ID is not specified then a list of waiting messages is returned instead. + +pop3://user:password@mail.example.com - This lists the available messages for +the user + +pop3://user:password@mail.example.com/1 - This retrieves the first message for +the user + +.IP IMAP +The path part of an IMAP request not only specifies the mailbox to list (Added +in 7.30.0) or select, but can also be used to check the UIDVALIDITY of the +mailbox, to specify the UID, SECTION (Added in 7.30.0) and PARTIAL octets +(Added in 7.37.0) of the message to fetch and to specify what nessages to +search for (Added in 7.37.0). + +imap://user:password@mail.example.com - Performs a top level folder list + +imap://user:password@mail.example.com/INBOX - Performs a folder list on the +user's inbox + +imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the user's inbox +and fetches message 1 + +imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2 - Selects +the user's inbox, checks the UIDVALIDITY of the mailbox is 50 and fetches +message 2 if it is + +imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT - Selects the +user's inbox and fetches the text portial of message 3 + +imap://user:password@mail.example.com/INBOX/;UID=4/;PARTIAL=0.1024 - Selects +the user's inbox and fetches the first 1024 octets of message 4 + +imap://user:password@mail.example.com/INBOX?NEW - Selects the user's inbox and +checks for NEW messages + +imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows - Selects the +user's inbox and searches for messages containing "shadows" in the subject +line + +For more information about the individual components of an IMAP URL please +see RFC5092. + +.IP SCP +The path part of a SCP request specifies the file to retrieve and from what +directory. The file part may not be omitted. The file is taken as an absolute +path from the root directory on the server. To specify a path relative to the +user's home directory on the server, prepend ~/ to the path portion. If the +user name is not embedded in the URL, it can be set with the +\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option. + +scp://user@example.com/etc/issue - This specifies the file /etc/issue + +scp://example.com/~/my-file - This specifies the file my-file in the +user's home directory on the server + +.IP SFTP +The path part of a SFTP request specifies the file to retrieve and from what +directory. If the file part is omitted then libcurl downloads the directory +listing for the directory specified. If the path ends in a / then a directory +listing is returned instead of a file. If the path is omitted entirely then +the directory listing for the root / home directory will be returned. If the +user name is not embedded in the URL, it can be set with the +\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option. + +sftp://user:password@example.com/etc/issue - This specifies the file +/etc/issue + +sftp://user@example.com/~/my-file - This specifies the file my-file in the +user's home directory + +sftp://ssh.example.com/~/Documents/ - This requests a directory listing +of the Documents directory under the user's home directory + +.IP LDAP +The path part of a LDAP request can be used to specify the: Distinguished +Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field +is separated by a question mark and when that field is not required an empty +string with the question mark separator should be included. + +ldap://ldap.example.com/o=My%20Organisation - This will perform a LDAP search +with the DN as My Organisation. + +ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will perform +the same search but will only return postalAddress attributes. + +ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty DN +and requests information about the rootDomainNamingContext attribute for an +Active Directory server. + +For more information about the individual components of a LDAP URL please +see RFC4516. +.IP RTMP +There's no official URL spec for RTMP so libcurl uses the URL syntax supported +by the underlying librtmp library. It has a syntax where it wants a +traditional URL, followed by a space and a series of space-separated +name=value pairs. + +While space is not typically a "legal" letter, libcurl accepts them. When a +user wants to pass in a '#' (hash) character it will be treated as a fragment +and get cut off by libcurl if provided literally. You will instead have to +escape it by providing it as backslash and its ASCII value in hexadecimal: +"\\23". + +.IP NOTES +\fICURLOPT_URL(3)\fP is the only option that \fBmust\fP be set before a +transfer is started. + +\fICURLOPT_PROTOCOLS(3)\fP can be used to limit what protocols libcurl will +use for this transfer, independent of what libcurl has been compiled to +support. That may be useful if you accept the URL from an external source and +want to limit the accessibility. +.SH DEFAULT +There is no default URL. If this option isn't set, no transfer can be +performed. +.SH PROTOCOLS +All +.SH EXAMPLE +.nf + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); +.SH AVAILABILITY +POP3 and SMTP added in 7.31.0 +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_VERBOSE "(3), " CURLOPT_PROTOCOLS "(3), " +.BR curl_easy_perform "(3)" diff --git a/docs/libcurl/opts/CURLOPT_USERPWD.3 b/docs/libcurl/opts/CURLOPT_USERPWD.3 new file mode 100644 index 000000000..274c0a075 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_USERPWD.3 @@ -0,0 +1,64 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2014, 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_USERPWD 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_USERPWD \- set user + password to work with +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERPWD, char *userpwd); +.SH DESCRIPTION +Pass a char * as parameter, pointing to a zero terminated login details string +for the connection. The format of which is: [user name]:[password]. + +When using NTLM, you can set the domain by prepending it to the user name and +separating the domain and name with a forward (/) or backward slash (\\). Like +this: "domain/user:password" or "domain\\user:password". Some HTTP servers (on +Windows) support this style even for Basic authentication. + +When using HTTP and \fICURLOPT_FOLLOWLOCATION(3)\fP, libcurl might perform +several requests to possibly different hosts. libcurl will only send this user +and password information to hosts using the initial host name (unless +\fICURLOPT_UNRESTRICTED_AUTH(3)\fP is set), so if libcurl follows locations to +other hosts it will not send the user and password to those. This is enforced +to prevent accidental information leakage. + +Use \fICURLOPT_HTTPAUTH(3)\fP to specify the authentication method for HTTP +based connections or \fICURLOPT_LOGIN_OPTIONS(3)\fP to control IMAP, POP3 and +SMTP options. + +The user and password strings are not URL decoded, so there's no way to send +in a user name containing a colon using this option. Use +\fICURLOPT_USERNAME(3)\fP for that, or include it in the URL. +.SH DEFAULT +NULL +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_USERNAME "(3), " CURLOPT_PASSWORD "(3), " |