curl_easy_setopt.3

THIS IS HTTP CURL Example

pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV.

If the server is an IPv6 host, this option will have no effect as of 7.12.3.
.IP CURLOPT_FTP_CREATE_MISSING_DIRS
Pass a long. If the value is non-zero, curl will attempt to create any remote
directory that it fails to CWD into. CWD is the command that changes working
directory. (Added in 7.10.7)

This setting also applies to SFTP-connections. curl will attempt to create
the remote directory if it can't obtain a handle to the target-location. The
creation will fail if a file of the same name as the directory to create
already exists or lack of permissions prevents creation. (Added in 7.16.3)
.IP CURLOPT_FTP_RESPONSE_TIMEOUT
Pass a long.  Causes curl to set a timeout period (in seconds) on the amount
of time that the server is allowed to take in order to generate a response
message for a command before the session is considered hung.  While curl is
waiting for a response, this value overrides \fICURLOPT_TIMEOUT\fP. It is
recommended that if used in conjunction with \fICURLOPT_TIMEOUT\fP, you set
\fICURLOPT_FTP_RESPONSE_TIMEOUT\fP to a value smaller than
\fICURLOPT_TIMEOUT\fP.  (Added in 7.10.8)
.IP CURLOPT_FTP_ALTERNATIVE_TO_USER
Pass a char * as parameter, pointing to a string which will be used to
authenticate if the usual FTP "USER user" and "PASS password" negotiation
fails. This is currently only known to be required when connecting to
Tumbleweed's Secure Transport FTPS server using client certificates for
authentication. (Added in 7.15.5)
.IP CURLOPT_FTP_SKIP_PASV_IP
Pass a long. If set to a non-zero value, it instructs libcurl to not use the
IP address the server suggests in its 227-response to libcurl's PASV command
when libcurl connects the data connection. Instead libcurl will re-use the
same IP address it already uses for the control connection. But it will use
the port number from the 227-response. (Added in 7.14.2)

This option has no effect if PORT, EPRT or EPSV is used instead of PASV.
.IP CURLOPT_USE_SSL
Pass a long using one of the values from below, to make libcurl use your
desired level of SSL for the ftp transfer. (Added in 7.11.0)

(This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the constants
were known as CURLFTPSSL_*)
.RS
.IP CURLUSESSL_NONE
Don't attempt to use SSL.
.IP CURLUSESSL_TRY
Try using SSL, proceed as normal otherwise.
.IP CURLUSESSL_CONTROL
Require SSL for the control connection or fail with \fICURLE_USE_SSL_FAILED\fP.
.IP CURLUSESSL_ALL
Require SSL for all communication or fail with \fICURLE_USE_SSL_FAILED\fP.
.RE
.IP CURLOPT_FTPSSLAUTH
Pass a long using one of the values from below, to alter how libcurl issues
\&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated (see
\fICURLOPT_FTP_SSL\fP). (Added in 7.12.2)
.RS
.IP CURLFTPAUTH_DEFAULT
Allow libcurl to decide
.IP CURLFTPAUTH_SSL
Try "AUTH SSL" first, and only if that fails try "AUTH TLS"
.IP CURLFTPAUTH_TLS
Try "AUTH TLS" first, and only if that fails try "AUTH SSL"
.RE
.IP CURLOPT_FTP_SSL_CCC
If enabled, this option makes libcurl use CCC (Clear Command Channel). It
shuts down the SSL/TLS layer after authenticating. The rest of the
control channel communication will be unencrypted. This allows NAT routers
to follow the FTP transaction. Pass a long using one of the values below.
(Added in 7.16.1)
.RS
.IP CURLFTPSSL_CCC_NONE
Don't attempt to use CCC.
.IP CURLFTPSSL_CCC_PASSIVE
Do not initiate the shutdown, but wait for the server to do it. Do not send
a reply.
.IP CURLFTPSSL_CCC_ACTIVE
Initiate the shutdown and wait for a reply.
.RE
.IP CURLOPT_FTP_ACCOUNT
Pass a pointer to a zero-terminated string (or NULL to disable). When an FTP
server asks for "account data" after user name and password has been provided,
this data is sent off using the ACCT command. (Added in 7.13.0)
.IP CURLOPT_FTP_FILEMETHOD
Pass a long that should have one of the following values. This option controls
what method libcurl should use to reach a file on a FTP(S) server. The
argument should be one of the following alternatives:
.RS
.IP CURLFTPMETHOD_MULTICWD
libcurl does a single CWD operation for each path part in the given URL. For
deep hierarchies this means very many commands. This is how RFC1738 says it
should be done. This is the default but the slowest behavior.
.IP CURLFTPMETHOD_NOCWD
libcurl does no CWD at all. libcurl will do SIZE, RETR, STOR etc and give a
full path to the server for all these commands. This is the fastest behavior.
.IP CURLFTPMETHOD_SINGLECWD
libcurl does one CWD with the full target directory and then operates on the
file \&"normally" (like in the multicwd case). This is somewhat more standards
compliant than 'nocwd' but without the full penalty of 'multicwd'.
.RE
.SH PROTOCOL OPTIONS
.IP CURLOPT_TRANSFERTEXT
A non-zero parameter tells the library to use ASCII mode for ftp transfers,
instead of the default binary transfer. For win32 systems it does not set the
stdout to binary mode. This option can be usable when transferring text data
between systems with different views on certain characters, such as newlines
or similar.

libcurl does not do a complete ASCII conversion when doing ASCII transfers
over FTP. This is a known limitation/flaw that nobody has rectified. libcurl
simply sets the mode to ascii and performs a standard transfer.
.IP CURLOPT_PROXY_TRANSFER_MODE
Pass a long. If the value is set to 1 (one), it tells libcurl to set the
transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by
appending ;type=a or ;type=i to the URL. Without this setting, or it being
set to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when
doing FTP via a proxy. Beware that not all proxies support this feature.
(Added in 7.18.0)
.IP CURLOPT_CRLF
Convert Unix newlines to CRLF newlines on transfers.
.IP CURLOPT_RANGE
Pass a char * as parameter, which should contain the specified range you
want. It should be in the format "X-Y", where X or Y may be left out. 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). Pass a NULL to this option to disable the use of ranges.

Ranges work on HTTP, FTP and FILE (since 7.18.0) transfers only.
.IP CURLOPT_RESUME_FROM
Pass a long as parameter. It contains the offset in number of bytes that you
want the transfer to start from. Set this option to 0 to make the transfer
start from the beginning (effectively disabling resume). For FTP, set this
option to -1 to make the transfer start from the end of the target file
(useful to continue an interrupted upload).
.IP CURLOPT_RESUME_FROM_LARGE
Pass a curl_off_t as parameter. It contains the offset in number of bytes that
you want the transfer to start from. (Added in 7.11.0)
.IP CURLOPT_CUSTOMREQUEST
Pass a pointer to a zero terminated string as parameter. It will be used
instead of GET or HEAD when doing an HTTP request, or instead of LIST or NLST
when doing an ftp directory listing. This is useful for doing DELETE or other
more or less obscure HTTP requests. Don't do this at will, make sure your
server supports the command first.

Note that libcurl will still act and assume the keyword it would use if you
didn't set your custom one is the one in use and it will act according to
that. Thus, changing this to a HEAD when libcurl otherwise would do a GET
might cause libcurl to act funny, and similar. To switch to a proper HEAD, use
\fICURLOPT_NOBODY\fP, to switch to a proper POST, use \fICURLOPT_POST\fP or
\fICURLOPT_POSTFIELDS\fP and so on.

Restore to the internal default by setting this to NULL.

Many people have wrongly used this option to replace the entire request with
their own, including multiple headers and POST contents. While that might work
in many cases, it will cause libcurl to send invalid requests and it could
possibly confuse the remote server badly. Use \fICURLOPT_POST\fP and
\fICURLOPT_POSTFIELDS\fP to set POST data. Use \fICURLOPT_HTTPHEADER\fP to
replace or extend the set of headers sent by libcurl. Use
\fICURLOPT_HTTP_VERSION\fP to change HTTP version.
.IP CURLOPT_FILETIME
Pass a long. If it is a non-zero value, libcurl will attempt to get the
modification date of the remote document in this operation. This requires that
the remote server sends the time or replies to a time querying command. The
\fIcurl_easy_getinfo(3)\fP function with the \fICURLINFO_FILETIME\fP argument
can be used after a transfer to extract the received time (if any).
.IP CURLOPT_NOBODY
A non-zero parameter tells the library to not include the body-part in the
output. This is only relevant for protocols that have separate header and body
parts. On HTTP(S) servers, this will make libcurl do a HEAD request.

To change request to GET, you should use \fICURLOPT_HTTPGET\fP. Change request
to POST with \fICURLOPT_POST\fP etc.
.IP CURLOPT_INFILESIZE
When uploading a file to a remote site, this option should be used to tell
libcurl what the expected size of the infile is. This value should be passed
as a long. See also \fICURLOPT_INFILESIZE_LARGE\fP.

For uploading using SCP, this option or \fICURLOPT_INFILESIZE_LARGE\fP is
mandatory.

Note that this option does not limit how much data libcurl will actually send,
as that is controlled entirely by what the read callback returns.
.IP CURLOPT_INFILESIZE_LARGE
When uploading a file to a remote site, this option should be used to tell
libcurl what the expected size of the infile is.  This value should be passed
as a curl_off_t. (Added in 7.11.0)

For uploading using SCP, this option or \fICURLOPT_INFILESIZE\fP is mandatory.

Note that this option does not limit how much data libcurl will actually send,
as that is controlled entirely by what the read callback returns.
.IP CURLOPT_UPLOAD
A non-zero parameter tells the library to prepare for an upload. The
\fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP or
\fICURLOPT_INFILESIZE_LARGE\fP options are also interesting for uploads. If
the protocol is HTTP, uploading means using the PUT request unless you tell
libcurl otherwise.

Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual.

If you use PUT to a HTTP 1.1 server, you can upload data without knowing the
size before starting the transfer if you use chunked encoding. You enable this
by adding a header like "Transfer-Encoding: chunked" with
\fICURLOPT_HTTPHEADER\fP. With HTTP 1.0 or without chunked transfer, you must
specify the size.
.IP CURLOPT_MAXFILESIZE
Pass a long as parameter. This allows you to specify the maximum size (in
bytes) of a file to download. If the file requested is larger than this value,
the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned.

The file size is not always known prior to download, and for such files this
option has no effect even if the file transfer ends up being larger than this
given limit. This concerns both FTP and HTTP transfers.
.IP CURLOPT_MAXFILESIZE_LARGE
Pass a curl_off_t as parameter. This allows you to specify the maximum size
(in bytes) of a file to download. If the file requested is larger than this
value, the transfer will not start and \fICURLE_FILESIZE_EXCEEDED\fP will be
returned. (Added in 7.11.0)

The file size is not always known prior to download, and for such files this
option has no effect even if the file transfer ends up being larger than this
given limit. This concerns both FTP and HTTP transfers.
.IP CURLOPT_TIMECONDITION
Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE\fP time
value is treated. You can set this parameter to \fICURL_TIMECOND_IFMODSINCE\fP
or \fICURL_TIMECOND_IFUNMODSINCE\fP. This feature applies to HTTP and FTP.

The last modification time of a file is not always known and in such instances
this feature will have no effect even if the given time condition would have
not been met.
.IP CURLOPT_TIMEVALUE
Pass a long as parameter. This should be the time in seconds since 1 jan 1970,
and the time will be used in a condition as specified with
\fICURLOPT_TIMECONDITION\fP.
.SH CONNECTION OPTIONS
.IP CURLOPT_TIMEOUT
Pass a long as parameter containing 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 will cause curl to use the
SIGALRM to enable time-outing system calls.

In unix-like systems, this might cause signals to be used unless
\fICURLOPT_NOSIGNAL\fP is set.
.IP CURLOPT_TIMEOUT_MS
Like \fICURLOPT_TIMEOUT\fP but takes number of milliseconds instead.