generic-library/curl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

opts: 9 more options as separate man pages

Browse Source
This commit is contained in:
Daniel Stenberg 2014-06-17 18:04:40 +02:00
parent 0042557598
commit 0890bb6a51
9 changed files with 757 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 Normal file
View File

@ -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), "

58
docs/libcurl/opts/CURLOPT_INFILESIZE.3 Normal file
View File

@ -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), "

51
docs/libcurl/opts/CURLOPT_PORT.3 Normal file
View File

@ -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), "

84
docs/libcurl/opts/CURLOPT_PROXY.3 Normal file
View File

@ -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)"

49
docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 Normal file
View File

@ -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), "

54
docs/libcurl/opts/CURLOPT_RANGE.3 Normal file
View File

@ -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), "

57
docs/libcurl/opts/CURLOPT_TIMEOUT.3 Normal file
View File

@ -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), "

283
docs/libcurl/opts/CURLOPT_URL.3 Normal file
View File

@ -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)"

64
docs/libcurl/opts/CURLOPT_USERPWD.3 Normal file
View File

@ -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), "