CURLoption type

Definition: include pGUI.e

CURLoption identifier
-- or --
bool res = CURLoption(integer x)
Description: options for curl_easy_setopt() - note that types below for the third parameter are suggestive only; it is of course (always) an object, and certainly, for instance, when this page says string for that argument, an atom char* pointer is just as valid.

The options go from 1 to 244 (if you ignore the +k*10000 encoding it uses internally), with several no longer used.

The one-liners below with "See CURLOPT_XXX" have not been tested, or properly documented here (which is most of them!).
CURLoption A CURLoption is one of the following:
BEHAVIOR OPTIONS
CURLOPT_VERBOSE Synopsis: CURLcode res = curl_easy_setopt(atom curl, CURLOPT_VERBOSE, bool onoff)

Set verbose mode on/off. The parameter (onoff) should be 0/1 (or false/true). Default 0 (false), meaning disabled.

Set the onoff parameter to 1 (true) to make the library display a lot of verbose information about its operations on this handle.
Very useful for libcurl and/or protocol debugging and understanding.
The verbose information will be sent to stderr, or the stream set with CURLOPT_STDERR.

You hardly ever want this set in production use, you will almost always want this when you debug/report problems.

To also get all the protocol data sent and received, consider using the CURLOPT_DEBUGFUNCTION.

Protocols: All

Returns: CURLE_OK

See also: CURLOPT_STDERR, CURLOPT_DEBUGFUNCTION
CURLOPT_HEADER Include the header in the body output. See CURLOPT_HEADER
CURLOPT_NOPROGRESS Shut off the progress meter.

Synopsis: curl_easy_setopt(curl, CURLOPT_NOPROGRESS, bool onoff)

If onoff is set to true(1), it tells the library to shut off the progress meter completely for requests done with this handle.
It will also prevent the CURLOPT_XFERINFOFUNCTION or CURLOPT_PROGRESSFUNCTION from getting called.

Default: true(1), meaning it normally runs without a progress meter.

Protocols: All

Availability: Always

Return value: Returns CURLE_OK.

See also: CURLOPT_XFERINFOFUNCTION, CURLOPT_PROGRESSFUNCTION, CURLOPT_VERBOSE
CURLOPT_NOSIGNAL Do not install signal handlers. See CURLOPT_NOSIGNAL
CURLOPT_WILDCARDMATCH Transfer multiple files according to a file name pattern. See CURLOPT_WILDCARDMATCH
CALLBACK OPTIONS
CURLOPT_WRITEFUNCTION Callback for writing data.

Synopsis/Example:
include builtins/libcurl.e
 
function write_callback(atom pData, integer size, integer nmemb, atom pUserdata);
integer bytes_written = size*nmemb
    ... peek(pData,bytes_processed) ...
    return bytes_written
end function
constant write_cb = call_back({'+',routine_id("write_callback")})

curl_easy_setopt(atom curl, CURLOPT_WRITEFUNCTION, write_cb)

Pass a pointer to your callback function, which should match the prototype shown above.

This callback function gets called by libcurl as soon as there is data received that needs to be saved.
pData points to the delivered data, and the size of that data is size multiplied with nmemb.

The callback function will be passed as much data as possible in all invokes, but you must not make any assumptions.
It may be one byte, it may be thousands. The maximum amount of body data that will be passed to the write callback is defined in the curl.h header file: CURL_MAX_WRITE_SIZE (the usual default is 16K). If CURLOPT_HEADER is enabled, which makes header data get passed to the write callback, you can get up to CURL_MAX_HTTP_HEADER bytes (usually 100K).
Note that builtins\libcurl.e defines neither CURL_MAX_WRITE_SIZE nor CURL_MAX_HTTP_HEADER, since they would not reflect how the dll/so was built.

This function may be called with zero bytes data if the transferred file is empty.

The data passed to this function will not be zero terminated!

Set the pUserdata argument with the CURLOPT_WRITEDATA option.

Your callback should return the number of bytes actually taken care of.
If that amount differs from the amount passed to your callback function, it will signal an error condition to the library.
This will cause the transfer to get aborted and the libcurl function used will return CURLE_WRITE_ERROR.

If your callback function returns CURL_WRITEFUNC_PAUSE it will cause this transfer to become paused. See curl_easy_pause for further details.

Set this option to NULL to get the internal default function used instead of your callback.
The internal default function will write the data to the FILE * given with CURLOPT_WRITEDATA.

Default: libcurl will use 'fwrite' as a callback by default.

Protocols: All

Availability: Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.

Return value: This will return CURLE_OK.

See also: CURLOPT_WRITEDATA, CURLOPT_READFUNCTION
CURLOPT_WRITEDATA Custom data pointer to pass to the write callback.

Synopsis: curl_easy_setopt(curl, CURLOPT_WRITEDATA, atom pdata)

A data pointer to pass to the write callback.
If you use the CURLOPT_WRITEFUNCTION option, this is the pointer you get in that callback’s 4th argument.
If you don’t use a write callback, you must make pointer a 'FILE *' (cast to 'void *') as libcurl will pass this to fwrite(3) when writing data.
[PL: from a Phix/libcurl.e perspective, you cannot use results from open(), but you may be able to obtain handles for stderr etc, or perhaps even from something like builtins\VM\pfileioN.e that returns handles [see fdtbl] - all completely untested, of course.]
The internal CURLOPT_WRITEFUNCTION will write the data to the FILE * given with this option, or to stdout if this option has not been set.

If you are using libcurl as a win32 DLL, you MUST use the CURLOPT_WRITEFUNCTION if you set this option or you will experience crashes.

Default: By default, this is a FILE * to stdout.

Protocols: Used for all protocols.

Example: A common technique is to use the write callback to store the incoming data into a dynamically growing allocated buffer, and then this CURLOPT_WRITEDATA is used to point to a struct or the buffer to store data in.
[DEV see builtins/libcurl.e, curle_easy_perform_ex() for the basic idea, though that does not actually use CURLOPT_WRITEDATA. I should try and write a proper thread-safe example.]

Availability: Available in all libcurl versions. This option was formerly known as CURLOPT_FILE, the name CURLOPT_WRITEDATA was introduced in 7.9.7.

Return value: This will return CURLE_OK.

See also: CURLOPT_WRITEFUNCTION, CURLOPT_READDATA
CURLOPT_READFUNCTION Callback for reading data. See CURLOPT_READFUNCTION
CURLOPT_READDATA Data pointer to pass to the read callback. See CURLOPT_READDATA
CURLOPT_IOCTLFUNCTION Callback for I/O operations. See CURLOPT_IOCTLFUNCTION
CURLOPT_IOCTLDATA Data pointer to pass to the I/O callback. See CURLOPT_IOCTLDATA
CURLOPT_SEEKFUNCTION Callback for seek operations. See CURLOPT_SEEKFUNCTION
CURLOPT_SEEKDATA Data pointer to pass to the seek callback. See CURLOPT_SEEKDATA
CURLOPT_SOCKOPTFUNCTION Callback for sockopt operations. See CURLOPT_SOCKOPTFUNCTION
CURLOPT_SOCKOPTDATA Data pointer to pass to the sockopt callback. See CURLOPT_SOCKOPTDATA
CURLOPT_OPENSOCKETFUNCTION Callback for socket creation. See CURLOPT_OPENSOCKETFUNCTION
CURLOPT_OPENSOCKETDATA Data pointer to pass to the open socket callback. See CURLOPT_OPENSOCKETDATA
CURLOPT_CLOSESOCKETFUNCTION Callback for closing socket. See CURLOPT_CLOSESOCKETFUNCTION
CURLOPT_CLOSESOCKETDATA Data pointer to pass to the close socket callback. See CURLOPT_CLOSESOCKETDATA
CURLOPT_PROGRESSFUNCTION OBSOLETE callback for progress meter.

Synopsis/Example:
include builtins/libcurl.e
 
-- *** NB *** / needs checking on 64 bit... [DEV]
--int progress_callback(void *clientp, double dltotal, double dlnow, double ultotal, double ulnow);
function curl_progress_callback(atom clientp,
                                atom dltotal1, atom dltotal2,
                                atom dlnow1, atom dlnow2,
                                atom ultotal1, atom ultotal2, 
                                atom ulnow1, atom ulnow2)
    atom f64 = allocate(8), dltotal, dlnow, ultotal, ulnow

    -- convert to float64
    poke4(f64,{dltotal1, dltotal2})     dltotal = float64_to_atom(peek({f64,8}))
    poke4(f64,{dlnow1,   dlnow2})       dlnow   = float64_to_atom(peek({f64,8}))
    poke4(f64,{ultotal1, ultotal2})     ultotal = float64_to_atom(peek({f64,8}))
    poke4(f64,{ulnow1,   ulnow2})       ulnow   = float64_to_atom(peek({f64,8}))
    free(f64)

    atom pcnt = iff(dltotal=0?0:dlnow*100/dltotal)
    printf(1, "Current=%d kb  Total=%d kb (%d%%)\n  ", {dlnow/1024, dltotal/1024, pcnt})

    return 0 -- signify success
end function
constant progress_cb = call_back({'+', routine_id("curl_progress_callback")})

curl_easy_setopt(atom curl, CURLOPT_PROGRESSFUNCTION, progress_cb)

Note the routine actually gets passed a pointer and four doubles (64-bit floats). Callbacks get 32-bit args on 32-bit, which must be stitched back together into 64 bit floats.

Pass a pointer to your callback function, which should match the prototype shown above.

We encourage users to use the newer CURLOPT_XFERINFOFUNCTION instead, if you can.

This function gets called by libcurl instead of its internal equivalent with a frequent interval.
While data is being transferred it will be called very frequently, and during slow periods like when nothing is being transferred it can slow down to about one call per second.

clientp is the pointer set with CURLOPT_PROGRESSDATA, it is not used by libcurl but is only passed along from the application to the callback.

The callback gets told how much data libcurl will transfer and has transferred, in number of bytes.
dltotal is the total number of bytes libcurl expects to download in this transfer.
dlnow is the number of bytes downloaded so far.
ultotal is the total number of bytes libcurl expects to upload in this transfer.
ulnow is the number of bytes uploaded so far.

Unknown/unused argument values passed to the callback will be set to zero (like if you only download data, the upload size will remain 0).
Many times the callback will be called one or more times first, before it knows the data sizes so a program must be made to handle that.

Returning a non-zero value from this callback will cause libcurl to abort the transfer and return CURLE_ABORTED_BY_CALLBACK.

If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl function that performs transfers.

CURLOPT_NOPROGRESS must be set to 0 to make this function actually get called.

Default: By default, libcurl has an internal progress meter. That’s rarely wanted by users.

Protocols: All

Availability: Always

Return value: Returns CURLE_OK.

See also: CURLOPT_VERBOSE, CURLOPT_NOPROGRESS
CURLOPT_PROGRESSDATA Data pointer to pass to the progress meter callback. See CURLOPT_PROGRESSDATA
CURLOPT_XFERINFOFUNCTION Callback for progress meter.

Synopsis/Example:
include builtins/libcurl.e
 
-- *** NB WRONG *** / to be filled in... [DEV]
function write_callback(atom pData, integer size, integer nmemb, atom pUserdata);
integer bytes_written = size*nmemb
    ... peek(pData,bytes_processed) ...
    return bytes_written
end function
constant write_cb = call_back({'+',routine_id("write_callback")})

curl_easy_setopt(atom curl, CURLOPT_WRITEFUNCTION, write_cb)
--int progress_callback(void *clientp, curl_off_t dltotal, curl_off_t dlnow, 
--                                     curl_off_t ultotal, curl_off_t ulnow);
--CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XFERINFOFUNCTION, progress_callback);

Note the above assumes curl_off_t is int64. Callbacks get 32-bit args on 32-bit, which must be stitched together into int64s.

Pass a pointer to your callback function, which should match (one or both of?) the prototypes shown above.

This function gets called by libcurl instead of its internal equivalent with a frequent interval.
While data is being transferred it will be called very frequently, and during slow periods like when nothing is being transferred it can slow down to about one call per second.

clientp is the pointer set with CURLOPT_XFERINFODATA, it is not used by libcurl but is only passed along from the application to the callback.

The callback gets told how much data libcurl will transfer and has transferred, in number of bytes.
dltotal is the total number of bytes libcurl expects to download in this transfer.
dlnow is the number of bytes downloaded so far.
ultotal is the total number of bytes libcurl expects to upload in this transfer.
ulnow is the number of bytes uploaded so far.

Unknown/unused argument values passed to the callback will be set to zero (like if you only download data, the upload size will remain 0).
Many times the callback will be called one or more times first, before it knows the data sizes so a program must be made to handle that.

Returning a non-zero value from this callback will cause libcurl to abort the transfer and return CURLE_ABORTED_BY_CALLBACK.

If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl function that performs transfers.

CURLOPT_NOPROGRESS must be set to 0 to make this function actually get called.

Default: By default, libcurl has an internal progress meter. That’s rarely wanted by users.

Protocols: All

Availability: Added in 7.32.0. This callback replaces CURLOPT_PROGRESSFUNCTION

Return value: Returns CURLE_OK.

See also: CURLOPT_XFERINFODATA, CURLOPT_NOPROGRESS
CURLOPT_XFERINFODATA Data pointer to pass to the progress meter callback. See CURLOPT_XFERINFODATA
CURLOPT_HEADERFUNCTION Specify a callback that receives header data.

Synopsis/Example:
include builtins/libcurl.e
 
function header_callback(atom pData, integer size, integer nmemb, atom pUserdata);
integer bytes_processed = size*nmemb
    ... peek(pData,bytes_processed) ...
    return bytes_processed
end function
constant header_cb = call_back({'+',routine_id("header_callback")})

    curl_easy_setopt(atom curl, CURLOPT_HEADERFUNCTION, header_cb)

The specified function gets called by libcurl as soon as it has received header data.
The header callback will be called once for each header and only complete header lines are passed on to the callback.
Parsing headers is very easy using this. The size of the data pointed to by buffer is size multiplied with nmemb.
Do not assume that the header line is zero terminated!
The pointer named pUserdata is the one you set with the CURLOPT_HEADERDATA option.
This callback function must return the number of bytes actually taken care of.
If that amount differs from the amount passed in to your function, it will signal an error to the library.
This will cause the transfer to get aborted and the libcurl function in progress will return CURLE_WRITE_ERROR.

A complete HTTP header that is passed to this function can be up to CURL_MAX_HTTP_HEADER (100K) bytes.

If this option is not set, or if it is set to NULL, but CURLOPT_HEADERDATA is set to anything but NULL, the function used to accept response data will be used instead.
That is, it will be the function specified with CURLOPT_WRITEFUNCTION, or if it is not specified or NULL - the default, stream-writing function.

It is important to note that the callback will be invoked for the headers of all responses received after initiating a request and not just the final response.
This includes all responses which occur during authentication negotiation.
If you need to operate on only the headers from the final response, you will need to collect headers in the callback yourself and use HTTP status lines, for example, to delimit response boundaries.

When a server sends a chunked encoded transfer, it may contain a trailer.
That trailer is identical to a HTTP header and if such a trailer is received it is passed to the application using this callback as well.
There are several ways to detect it being a trailer and not an ordinary header:
1) it comes after the response-body.
2) it comes after the final header line (CR LF)
3) a Trailer: header among the regular response-headers mention what header(s) to expect in the trailer.

For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function will get called with the server responses to the commands that libcurl sends.

Default: Nothing.

Protocols: Used for all protocols with headers or meta-data concept: HTTP, FTP, POP3, IMAP, SMTP and more.

Availability: Always

Return value: Returns CURLE_OK

See also: CURLOPT_HEADERDATA, CURLOPT_WRITEFUNCTION
CURLOPT_HEADERDATA Data pointer to pass to the header callback. See CURLOPT_HEADERDATA
CURLOPT_DEBUGFUNCTION Callback for debug information. See CURLOPT_DEBUGFUNCTION
CURLOPT_DEBUGDATA Data pointer to pass to the debug callback. See CURLOPT_DEBUGDATA
CURLOPT_SSL_CTX_FUNCTION Callback for SSL context logic. See CURLOPT_SSL_CTX_FUNCTION
CURLOPT_SSL_CTX_DATA Data pointer to pass to the SSL context callback. See CURLOPT_SSL_CTX_DATA
CURLOPT_CONV_TO_NETWORK_FUNCTION Callback for code base conversion. See CURLOPT_CONV_TO_NETWORK_FUNCTION
CURLOPT_CONV_FROM_NETWORK_FUNCTION Callback for code base conversion. See CURLOPT_CONV_FROM_NETWORK_FUNCTION
CURLOPT_CONV_FROM_UTF8_FUNCTION Callback for code base conversion. See CURLOPT_CONV_FROM_UTF8_FUNCTION
CURLOPT_INTERLEAVEFUNCTION Callback for RTSP interleaved data. See CURLOPT_INTERLEAVEFUNCTION
CURLOPT_INTERLEAVEDATA Data pointer to pass to the RTSP interleave callback. See CURLOPT_INTERLEAVEDATA
CURLOPT_CHUNK_BGN_FUNCTION Callback for wildcard download start of chunk. See CURLOPT_CHUNK_BGN_FUNCTION
CURLOPT_CHUNK_END_FUNCTION Callback for wildcard download end of chunk. See CURLOPT_CHUNK_END_FUNCTION
CURLOPT_CHUNK_DATA Data pointer to pass to the chunk callbacks. See CURLOPT_CHUNK_DATA
CURLOPT_FNMATCH_FUNCTION Callback for wildcard matching. See CURLOPT_FNMATCH_FUNCTION
CURLOPT_FNMATCH_DATA Data pointer to pass to the wildcard matching callback. See CURLOPT_FNMATCH_DATA
CURLOPT_SUPPRESS_CONNECT_HEADERS Suppress proxy CONNECT response headers from user callbacks. See CURLOPT_SUPPRESS_CONNECT_HEADERS
ERROR OPTIONS
CURLOPT_ERRORBUFFER Set error message buffer.

Synopsis: curl_easy_setopt(curl, CURLOPT_ERRORBUFFER, pErrorBuffer)

Pass a pointer to a buffer that libcurl may store human readable error messages in on failures or problems.
This may be more helpful than just the return code from curl_easy_perform and related functions.
The buffer must be at least CURL_ERROR_SIZE bytes big.

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 curl_easy_cleanup() or you set the same option again to use a different pointer.

Consider CURLOPT_VERBOSE and CURLOPT_DEBUGFUNCTION 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.

Default: NULL

Protocols: All

Example:
atom pErrorBuffer = allocate(CURL_ERROR_SIZE)
curl_easy_setopt(atom curl, CURLOPT_ERRORBUFFER, pErrorBuffer)
...
curl_easy_cleanup(curl)
free(pErrorBuffer)

Availability: Always

Return value: Returns CURLE_OK

See also: CURLOPT_DEBUGFUNCTION, CURLOPT_VERBOSE, curl_easy_strerror, curl_multi_strerror, curl_share_strerror
CURLOPT_STDERR stderr replacement stream. See CURLOPT_STDERR
CURLOPT_FAILONERROR Fail on HTTP 4xx errors.

Synopsis: curl_easy_setopt(curl, CURLOPT_FAILONERROR, bool fail)

A parameter of true (1) tells the library to fail the request if the HTTP code returned is equal to or larger than 400.
The default action would be to return the page normally, ignoring that code.

This method is not fail-safe and there are occasions where non-successful response codes will slip through, especially when authentication is involved (response codes 401 and 407).

You might get some amounts of headers transferred before this situation is detected, like when a "100-continue" is received as a response to a POST/PUT and a 401 or 407 is received immediately afterwards.

When this option is used and an error is detected, it will cause the connection to get closed and CURLE_HTTP_RETURNED_ERROR is returned.

Default: false (0), do not fail on error.

Protocols: HTTP

Example:
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/")
curl_easy_setopt(curl, CURLOPT_FAILONERROR, true)
CURLcode ret = curl_easy_perform(curl)
if ret=CURLE_HTTP_RETURNED_ERROR then
    /* a HTTP response error problem */
end if
Availability: Along with HTTP.

Return value: Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not.

See also: CURLOPT_HTTP200ALIASES, CURLOPT_KEEP_SENDING_ON_ERROR
CURLOPT_KEEP_SENDING_ON_ERROR Keep sending on HTTP >= 300 errors. CURLOPT_KEEP_SENDING_ON_ERROR
NETWORK OPTIONS
CURLOPT_URL Synopsis: CURLcode res = curl_easy_setopt(atom curl, CURLOPT_URL, string URL)

Specify the URL to work with. The parameter should be a string (or char *) which must be URL-encoded in the following format:

scheme://host:port/path

For a greater explanation of the format please see RFC 3986.

libcurl doesn’t validate the syntax or use this variable until the transfer is issued.
Even if you set a crazy value here, curl_easy_setopt will still return CURLE_OK.

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 CURLOPT_DEFAULT_PROTOCOL 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 CURLE_UNSUPPORTED_PROTOCOL will be returned from either the curl_easy_perform or curl_multi_perform functions when you call them.
Use curl_version_info for detailed information of which protocols are supported by the build of libcurl you are using.

CURLOPT_PROTOCOLS 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.

CURLOPT_URL is the only option that must be set before a transfer is started.

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

smb://domain%2fuser:password@server.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 RFC 2384, RFC 5092 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/ - [1]

smtp://mail.example.com:587/ - [2]
            
[1] This will connect to a web server using port 8080 rather than 80.
[2] 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:

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 - [1]

http://www.example.com/index.html - [2]

http://www.example.com/contactus/ - [3]
            
[1] This gets the main page from the web server.
[2] This returns the main page by explicitly requesting it.
[3] This returns the default document from the contactus directory.

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 - [1]

ftp://ftp.example.com/readme.txt - [2]

ftp://ftp.example.com/libcurl/readme.txt - [3]

ftp://user:password@ftp.example.com/readme.txt - [4]

ftp://user:password@ftp.example.com//readme.txt - [5]
            
[1] This retrieves the directory listing for the root directory.
[2] This downloads the file readme.txt from the root directory.
[3] This downloads readme.txt from the libcurl directory.
[4] 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.
[5] This retrieves the readme.txt from the root directory when logging in as a specified user.

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 - [1]

smtp://mail.example.com/client.example.com - [2]
            
[1] This connects to the mail server at example.com and sends your local computer’s host name in the HELO / EHLO command.
[2] This will send client.example.com in the HELO / EHLO command to the mail server at example.com.

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 - [1]

pop3://user:password@mail.example.com/1 - [2]
            
[1] This lists the available messages for the user
[2] This retrieves the first message for the user

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 messages to search for (Added in 7.37.0).
imap://user:password@mail.example.com - [1]

imap://user:password@mail.example.com/INBOX - [2]

imap://user:password@mail.example.com/INBOX/;UID=1 - [3]

imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2 - [4]

imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT - [5]

imap://user:password@mail.example.com/INBOX/;UID=4/;PARTIAL=0.1024 - [6]

imap://user:password@mail.example.com/INBOX?NEW - [7]

imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows - [8]
            
[1] Performs a top level folder list
[2] Performs a folder list on the user’s inbox
[3] Selects the user’s inbox and fetches message 1
[4] Selects the user’s inbox, checks the UIDVALIDITY of the mailbox is 50 and fetches message 2 if it is
[5] Selects the user’s inbox and fetches the text portion of message 3
[6] Selects the user’s inbox and fetches the first 1024 octets of message 4
[7] Selects the user’s inbox and checks for NEW messages
[8] 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 RFC 5092.

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 CURLOPT_USERPWD or CURLOPT_USERNAME option.
scp://user@example.com/etc/issue - [1]

scp://example.com/~/my-file - [2]
            
[1] This specifies the file /etc/issue
[2] This specifies the file my-file in the user’s home directory on the server

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 CURLOPT_USERPWD or CURLOPT_USERNAME option.
sftp://user:password@example.com/etc/issue - [1]

sftp://user@example.com/~/my-file - [2]

sftp://ssh.example.com/~/Documents/ - [3]
            
[1] This specifies the file /etc/issue
[2] This specifies the file my-file in the user’s home directory
[3] This requests a directory listing of the Documents directory under the user’s home directory

SMB

The path part of a SMB request specifies the file to retrieve and from what share and directory or the share to upload to and as such, may not be omitted.
If the user name is not embedded in the URL, it can be set with the CURLOPT_USERPWD or CURLOPT_USERNAME option.
If the user name is embedded in the URL then it must contain the domain name and as such, the backslash must be URL encoded as %2f.
smb://server.example.com/files/issue - [1]

smb://server.example.com/files/ -T issue - [2]
            
[1] This specifies the file "issue" located in the root of the "files" share
[2] This specifies the file "issue" will be uploaded to the root of the "files" share.

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 - [1]

ldap://ldap.example.com/o=My%20Organisation?postalAddress - [2]

ldap://ldap.example.com/?rootDomainNamingContext - [3]
            
[1] This will perform a LDAP search with the DN as My Organisation.
[2] This will perform the same search but will only return postalAddress attributes.
[3] 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 RFC 4516.

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".

The application does not have to keep the string around after setting this option.

DEFAULT

There is no default URL. If this option isn’t set, no transfer can be performed.

SECURITY CONCERNS

Applications may at times find it convenient to allow users to specify URLs for various purposes and that string would then end up fed to this option.

Getting a URL from an external untrusted party will bring reasons for several security concerns:

If you have an application that runs as or in a server application, getting an unfiltered URL can easily trick your application to access a local resource instead of a remote. Protecting yourself against localhost accesses is very hard when accepting user provided URLs.

Such custom URLs can also access other ports than you planned as port numbers are part of the regular URL format.
The combination of a local host and a custom port number can allow external users to play tricks with your local services.

Accepting external URLs may also use other protocols than http:// or other common ones. Restrict what accept with CURLOPT_PROTOCOLS.

User provided URLs can also be made to point to sites that redirect further on (possibly to other protocols too).
Consider your CURLOPT_FOLLOWLOCATION and CURLOPT_REDIR_PROTOCOLS settings.

Protocols: All

Availability: POP3 and SMTP were added in 7.31.0

Return value: Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient heap space.

Note that curl_easy_setopt won’t actually parse the given string so given a bad URL, it will not be detected until curl_easy_perform or similar is called.

See also: CURLOPT_VERBOSE, CURLOPT_PROTOCOLS, CURLOPT_FORBID_REUSE, CURLOPT_FRESH_CONNECT, curl_easy_perform, CURLINFO_REDIRECT_URL, CURLOPT_PATH_AS_IS
CURLOPT_PATH_AS_IS Disable squashing /../ and /./ sequences in the path. See CURLOPT_PATH_AS_IS
CURLOPT_PROTOCOLS Allowed protocols. See CURLOPT_PROTOCOLS
CURLOPT_REDIR_PROTOCOLS Protocols to allow redirects to. See CURLOPT_REDIR_PROTOCOLS
CURLOPT_DEFAULT_PROTOCOL Default protocol. See CURLOPT_DEFAULT_PROTOCOL
CURLOPT_PROXY Proxy to use. See CURLOPT_PROXY Synopsis: CURLcode res = curl_easy_setopt(atom curl, CURLOPT_PROXY, string proxy)

Set the proxy to use for the upcoming request. The parameter should be a string (or char *) holding the host name or dotted numerical IP address.
A numerical IPv6 address must be written within [brackets].

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 CURLOPT_PROXYPORT.
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.
http:// - HTTP Proxy. Default when no scheme or proxy type is specified.
https:// - HTTPS Proxy. (Added in 7.52.0 for OpenSSL, GnuTLS and NSS)
socks4:// - SOCKS4 Proxy.
socks4a:// - SOCKS4a Proxy. Proxy resolves URL hostname.
socks5:// - SOCKS5 Proxy.
socks5h:// - SOCKS5 Proxy. Proxy resolves URL hostname.

Without a scheme prefix, CURLOPT_PROXYTYPE 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 CURLOPT_QUOTE and similar FTP specifics that don’t work unless you tunnel through the HTTP proxy. Such tunneling is activated with CURLOPT_HTTPPROXYTUNNEL.

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 can also include protocol scheme (http://) and embedded user + password.

The application does not have to keep the string around after setting this option.

Environment variables

libcurl respects the proxy environment variables named http_proxy, ftp_proxy, sftp_proxy etc.
If set, libcurl will use the specified proxy for that URL scheme.
So for a "FTP://" URL, the ftp_proxy is considered.
all_proxy is used if no protocol specific proxy was set.

If no_proxy (or NO_PROXY) is set, it can specify a list of host names to not use a proxy for (even if one of the previous mention variables are set).
That is the exact equivalent of setting the CURLOPT_NOPROXY option.

The CURLOPT_PROXY and CURLOPT_NOPROXY options override environment variables.

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!

Protocols: All except file://. Note that some protocols don’t do very well over proxy.

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".
Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return error.

Return value: Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space.

See also: CURLOPT_PROXYPORT, CURLOPT_HTTPPROXYTUNNEL, CURLOPT_PROXYTYPE
CURLOPT_PRE_PROXY Socks proxy to use. See CURLOPT_PRE_PROXY
CURLOPT_PROXYPORT Proxy port to use. See CURLOPT_PROXYPORT
CURLOPT_PROXYTYPE Synopsis: CURLcode res = curl_easy_setopt(atom curl, CURLOPT_PROXYTYPE, integer proxytype)

Pass one of the values below to set the type of the proxy.
CURLPROXY_HTTP - HTTP Proxy. Default.
CURLPROXY_HTTPS - HTTPS Proxy. (Added in 7.52.0 for OpenSSL, GnuTLS and NSS)
CURLPROXY_HTTP_1_0 - HTTP 1.0 Proxy. This is very similar to CURLPROXY_HTTP except it uses HTTP/1.0 for any CONNECT tunnelling.
It does not change the HTTP version of the actual HTTP requests, controlled by CURLOPT_HTTP_VERSION.
CURLPROXY_SOCKS4 - SOCKS4 Proxy.
CURLPROXY_SOCKS4A - SOCKS4a Proxy. Proxy resolves URL hostname.
CURLPROXY_SOCKS5 - SOCKS5 Proxy.
CURLPROXY_SOCKS5_HOSTNAME - SOCKS5 Proxy. Proxy resolves URL hostname.

Often it is more convenient to specify the proxy type with the scheme part of the CURLOPT_PROXY string.

Default: CURLPROXY_HTTP

Protocols: Most

Return value: Returns CURLE_OK

See also: CURLOPT_PROXY, CURLOPT_PROXYPORT
CURLOPT_NOPROXY Filter out hosts from proxy use. CURLOPT_NOPROXY
CURLOPT_HTTPPROXYTUNNEL Tunnel through the HTTP proxy. CURLOPT_HTTPPROXYTUNNEL
CURLOPT_CONNECT_TO Connect to a specific host and port. See CURLOPT_CONNECT_TO
CURLOPT_SOCKS5_AUTH Socks5 authentication methods. See CURLOPT_SOCKS5_AUTH
CURLOPT_SOCKS5_GSSAPI_SERVICE Socks5 GSSAPI service name. CURLOPT_SOCKS5_GSSAPI_SERVICE
CURLOPT_SOCKS5_GSSAPI_NEC Socks5 GSSAPI NEC mode. See CURLOPT_SOCKS5_GSSAPI_NEC
CURLOPT_PROXY_SERVICE_NAME Proxy authentication service name. CURLOPT_PROXY_SERVICE_NAME
CURLOPT_SERVICE_NAME Authentication service name. CURLOPT_SERVICE_NAME
CURLOPT_INTERFACE Bind connection locally to this. See CURLOPT_INTERFACE
CURLOPT_LOCALPORT Bind connection locally to this port. See CURLOPT_LOCALPORT
CURLOPT_LOCALPORTRANGE Bind connection locally to port range. See CURLOPT_LOCALPORTRANGE
CURLOPT_DNS_CACHE_TIMEOUT Timeout for DNS cache. See CURLOPT_DNS_CACHE_TIMEOUT
CURLOPT_DNS_USE_GLOBAL_CACHE OBSOLETE Enable global DNS cache. See CURLOPT_DNS_USE_GLOBAL_CACHE
CURLOPT_BUFFERSIZE Ask for alternate buffer size. See CURLOPT_BUFFERSIZE
CURLOPT_PORT Port number to connect to. See CURLOPT_PORT
CURLOPT_TCP_FASTOPEN Enable TFO, TCP Fast Open. See CURLOPT_TCP_FASTOPEN
CURLOPT_TCP_NODELAY Disable the Nagle algorithm. See CURLOPT_TCP_NODELAY
CURLOPT_ADDRESS_SCOPE IPv6 scope for local addresses. See CURLOPT_ADDRESS_SCOPE
CURLOPT_TCP_KEEPALIVE Enable TCP keep-alive. See CURLOPT_TCP_KEEPALIVE
CURLOPT_TCP_KEEPIDLE Idle time before sending keep-alive. See CURLOPT_TCP_KEEPIDLE
CURLOPT_TCP_KEEPINTVL Interval between keep-alive probes. See CURLOPT_TCP_KEEPINTVL
CURLOPT_UNIX_SOCKET_PATH Path to a Unix domain socket. See CURLOPT_UNIX_SOCKET_PATH
CURLOPT_ABSTRACT_UNIX_SOCKET Path to an abstract Unix domain socket. See CURLOPT_ABSTRACT_UNIX_SOCKET
NAMES and PASSWORDS OPTIONS (Authentication)
CURLOPT_NETRC Enable .netrc parsing. See CURLOPT_NETRC
CURLOPT_NETRC_FILE .netrc file name. See CURLOPT_NETRC_FILE
CURLOPT_USERPWD Set the user name and password to use in authentication.

Synopsis: curl_easy_setopt(curl, CURLOPT_USERPWD, string userpwd)

Pass a string (or char *) as parameter, pointing to a login details string for the connection, the format of which is: <user name>:<password>.

When using Kerberos V5 authentication with a Windows based server, you should specify the user name part with the domain name in order for the server to successfully obtain a Kerberos Ticket. If you don’t then the initial part of the authentication handshake may fail.

When using NTLM, the user name can be specified simply as the user name without the domain name should the server be part of a single domain and forest.

To specify the domain name use either Down-Level Logon Name or UPN (User Principal Name) formats. For example, EXAMPLE\user and user@example.com respectively.

Some HTTP servers (on Windows) support inclusion of the domain for Basic authentication as well.

When using HTTP and CURLOPT_FOLLOWLOCATION, 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 CURLOPT_UNRESTRICTED_AUTH 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 CURLOPT_HTTPAUTH to specify the authentication method for HTTP based connections or CURLOPT_LOGIN_OPTIONS 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 CURLOPT_USERNAME for that, or include it in the URL.

The application does not have to keep the string around after setting this option.

Default: NULL

Protocols: Most

Example: curl_easy_setopt(curl, CURLOPT_USERPWD, "clark:kent")

Availability: Always

Return value: Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient heap space.

See also: CURLOPT_USERNAME, CURLOPT_PASSWORD, CURLOPT_PROXYUSERPWD
CURLOPT_PROXYUSERPWD Proxy user name and password. See CURLOPT_PROXYUSERPWD
CURLOPT_USERNAME User name. See CURLOPT_USERNAME
CURLOPT_PASSWORD Password. See CURLOPT_PASSWORD
CURLOPT_LOGIN_OPTIONS Login options. See CURLOPT_LOGIN_OPTIONS
CURLOPT_PROXYUSERNAME Proxy user name. See CURLOPT_PROXYUSERNAME
CURLOPT_PROXYPASSWORD Proxy password. See CURLOPT_PROXYPASSWORD
CURLOPT_HTTPAUTH HTTP server authentication methods. See CURLOPT_HTTPAUTH
CURLOPT_TLSAUTH_USERNAME TLS authentication user name. See CURLOPT_TLSAUTH_USERNAME
CURLOPT_PROXY_TLSAUTH_USERNAME Proxy TLS authentication user name. See CURLOPT_PROXY_TLSAUTH_USERNAME
CURLOPT_TLSAUTH_PASSWORD TLS authentication password. See CURLOPT_TLSAUTH_PASSWORD
CURLOPT_PROXY_TLSAUTH_PASSWORD Proxy TLS authentication password. See CURLOPT_PROXY_TLSAUTH_PASSWORD
CURLOPT_TLSAUTH_TYPE TLS authentication methods. See CURLOPT_TLSAUTH_TYPE
CURLOPT_PROXY_TLSAUTH_TYPE Proxy TLS authentication methods. See CURLOPT_PROXY_TLSAUTH_TYPE
CURLOPT_PROXYAUTH HTTP proxy authentication methods. See CURLOPT_PROXYAUTH
CURLOPT_SASL_IR Enable SASL initial response. See CURLOPT_SASL_IR
CURLOPT_XOAUTH2_BEARER OAuth2 bearer token. See CURLOPT_XOAUTH2_BEARER
HTTP OPTIONS
CURLOPT_AUTOREFERER Automatically set Referer: header. See CURLOPT_AUTOREFERER
CURLOPT_ACCEPT_ENCODING Accept-Encoding and automatic decompressing data. See CURLOPT_ACCEPT_ENCODING
CURLOPT_TRANSFER_ENCODING Request Transfer-Encoding. See CURLOPT_TRANSFER_ENCODING
CURLOPT_FOLLOWLOCATION Follow HTTP 3xx redirects.

Synopsis: curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, bool enable)

A parameter of true (1) tells the library to follow any Location: header that the server sends as part of a HTTP header in a 3xx response.
The Location: header can specify a relative or an absolute URL to follow.

libcurl will issue another request for the new URL and follow new Location: headers all the way until no more such headers are returned.
CURLOPT_MAXREDIRS can be used to limit the number of redirects libcurl will follow.

libcurl limits what protocols it automatically follows to.
The accepted protocols are set with CURLOPT_REDIR_PROTOCOLS.
By default libcurl will allow all protocols on redirect except those disabled for security reasons: Since 7.19.4 FILE and SCP are disabled, and since 7.40.0 SMB and SMBS are also disabled.

When following a Location:, the 3xx response code that redirected it also dictates which request method it will use in the subsequent request: For 301, 302 and 303 responses libcurl will switch method to GET unless CURLOPT_POSTREDIR instructs libcurl otherwise.
All other 3xx codes will make libcurl send the same method again.

For users who think the existing location following is too naive, too simple or just lacks features, it is very easy to instead implement your own redirect follow logic with the use of curl_easy_getinfo’s CURLINFO_REDIRECT_URL option instead of using CURLOPT_FOLLOWLOCATION.

Default: false (0), disabled

Protocols: HTTP(S)

Example
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/")
/* example.com is redirected, so we tell libcurl to follow redirection */
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, true)
CURLcode ret = curl_easy_perform(curl)

Availability: Along with HTTP

Return value: Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.

See also: CURLOPT_REDIR_PROTOCOLS, CURLOPT_PROTOCOLS, CURLOPT_POSTREDIR, CURLINFO_REDIRECT_URL, CURLINFO_REDIRECT_COUNT
CURLOPT_UNRESTRICTED_AUTH Do not restrict authentication to original host. CURLOPT_UNRESTRICTED_AUTH
CURLOPT_MAXREDIRS Maximum number of redirects to follow. See CURLOPT_MAXREDIRS
CURLOPT_POSTREDIR How to act on redirects after POST. See CURLOPT_POSTREDIR
CURLOPT_PUT Issue a HTTP PUT request. See CURLOPT_PUT
CURLOPT_POST Issue a HTTP POST request.

Synopsis: curl_easy_setopt(curl, CURLOPT_POST, bool post)

A parameter set to true(1) tells libcurl to do a regular HTTP post.
This will also make the library use a "Content-Type: application/x-www-form-urlencoded" header.
(This is by far the most commonly used POST method).

Use one of CURLOPT_POSTFIELDS or CURLOPT_COPYPOSTFIELDS options to specify what data to post and CURLOPT_POSTFIELDSIZE or CURLOPT_POSTFIELDSIZE_LARGE to set the data size.

Optionally, you can provide data to POST using the CURLOPT_READFUNCTION and CURLOPT_READDATA options but then you must make sure to not set CURLOPT_POSTFIELDS to anything but NULL.
When providing data with a callback, you must transmit it using chunked transfer-encoding or you must set the size of the data with the CURLOPT_POSTFIELDSIZE or CURLOPT_POSTFIELDSIZE_LARGE options.
To enable chunked encoding, you simply pass in the appropriate Transfer-Encoding header, see the post-callback.c example.

You can override the default POST Content-Type: header by setting your own with CURLOPT_HTTPHEADER.

Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
You can disable this header with CURLOPT_HTTPHEADER as usual.

If you use POST to a HTTP 1.1 server, you can send data without knowing the size before starting the POST if you use chunked encoding.
You enable this by adding a header like "Transfer-Encoding: chunked" with CURLOPT_HTTPHEADER.
With HTTP 1.0 or without chunked transfer, you must specify the size in the request.

When setting CURLOPT_POST to 1, it will automatically set CURLOPT_NOBODY to 0.

If you issue a POST request and then want to make a HEAD or GET using the same re-used handle, you must explicitly set the new request type using CURLOPT_NOBODY or CURLOPT_HTTPGET or similar.

Default: false(0), disabled

Protocols: HTTP

Example
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/foo.bin")
curl_easy_setopt(curl, CURLOPT_POST, true)
 
/* set up the read callback with CURLOPT_READFUNCTION */
 
ret = curl_easy_perform(curl)
 
curl_easy_cleanup(curl)

Availability: Along with HTTP

Return value: Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.

See also: CURLOPT_POSTFIELDS, CURLOPT_HTTPPOST
CURLOPT_POSTFIELDS Specify data to POST to server.

Synopsis: curl_easy_setopt(curl, CURLOPT_POSTFIELDS, nullable_string postdata)

Specify the full data to send in a HTTP POST operation.
You must make sure that the data is formatted the way you want the server to receive it.
libcurl will not convert or encode it for you in any way.
For example, the web server may assume that this data is url-encoded.

The data pointed to is NOT copied by the library: as a consequence, it must be preserved by the calling application until the associated transfer finishes.
This behaviour can be changed (so libcurl does copy the data) by setting the CURLOPT_COPYPOSTFIELDS option.

This POST is a normal application/x-www-form-urlencoded kind (and libcurl will set that Content-Type by default when this option is used), which is commonly used by HTML forms.
Change Content-Type with CURLOPT_HTTPHEADER.

You can use curl_easy_escape to url-encode your data, if necessary.
It returns a pointer to an encoded string that can be passed as postdata.

Using CURLOPT_POSTFIELDS implies CURLOPT_POST.

If CURLOPT_POSTFIELDS is explicitly set to NULL then libcurl will get the POST data from the read callback.
If you want to send a zero-byte POST set CURLOPT_POSTFIELDS to an empty string, or set CURLOPT_POST to 1 and CURLOPT_POSTFIELDSIZE to 0.

Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header, and libcurl will add that header automatically if the POST is either known to be larger than 1024 bytes or if the expected size is unknown.
You can disable this header with CURLOPT_HTTPHEADER as usual.

To make multipart/formdata posts (aka RFC 2388-posts), check out the CURLOPT_HTTPPOST option combined with curl_formadd.

Default: NULL

Protocols: HTTP

Example:
atom curl = curl_easy_init()
string data = "data to send"
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
/* size of the POST data */
curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, length(data))
/* pass in a pointer to the data - libcurl will not copy */
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data)
curl_easy_perform(curl)

Availability: Always

Return value: Returns CURLE_OK

See also: CURLOPT_POSTFIELDSIZE, CURLOPT_READFUNCTION
CURLOPT_POSTFIELDSIZE The POST data is this big.

Synopsis: curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, integer postdatasize)

If you want to post data to the server without having libcurl do a strlen() to measure the data size, this option must be used.
When this option is used you can post fully binary data, which otherwise is likely to fail.
If set to -1, the library will use strlen() to get the size.

If you post more than 2GB, use CURLOPT_POSTFIELDSIZE_LARGE.

Default: -1

Protocols: HTTP

Example:
atom curl = curl_easy_init()
string data = "data to send"
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com")
/* size of the POST data */
curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, length(data)) 
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data)
curl_easy_perform(curl)

Availability: Along with HTTP

Return value: Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.

See also: CURLOPT_POSTFIELDS, CURLOPT_POSTFIELDSIZE_LARGE
CURLOPT_POSTFIELDSIZE_LARGE The POST data is this big. See CURLOPT_POSTFIELDSIZE_LARGE
CURLOPT_COPYPOSTFIELDS Send a POST with this data - and copy it. See CURLOPT_COPYPOSTFIELDS
CURLOPT_HTTPPOST Multipart formpost HTTP POST. See CURLOPT_HTTPPOST
CURLOPT_REFERER Referer: header. See CURLOPT_REFERER
CURLOPT_USERAGENT Set HTTP user-agent header.

Synopsis: curl_easy_setopt(curl, CURLOPT_USERAGENT, string user_agent)

The string will be used to set the User-Agent: header in the HTTP request sent to the remote server.
This can be used to fool servers or scripts.
You can also set any custom header with CURLOPT_HTTPHEADER.

The application does not have to keep the string around after setting this option.

Default: NULL, no User-Agent: header is used by default.

Protocols: HTTP, HTTPS

Example:
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com")
curl_easy_setopt(curl, CURLOPT_USERAGENT, "Dark Secret Ninja/1.0")
curl_easy_perform(curl)

Availability: As long as HTTP is supported

Return value: Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space.

See also: CURLOPT_REFERER, CURLOPT_HTTPHEADER
CURLOPT_HTTPHEADER Set custom HTTP headers.

Synopsis: curl_easy_setopt(curl, CURLOPT_HTTPHEADER, atom headers)

Pass an slist (linked list of strings) of HTTP headers to pass to the server and/or proxy in your HTTP request.
The same list can be used for both host and proxy requests!

The linked list should be a fully valid list of struct curl_slist structs properly filled in.
Use curl_slist_append to create the list and curl_slist_free_all to clean up an entire list.
If you add a header that is otherwise generated and used by libcurl internally, your added one will be used instead.
If you add a header with no content as in 'Accept:' (no data on the right side of the colon), the internally used header will get disabled.
With this option you can add new headers, replace internal headers and remove internal headers.
To add a header with no content (nothing to the right side of the colon), use the form 'MyHeader;' (note the ending semicolon).

The headers included in the linked list must not be CRLF-terminated, because libcurl adds CRLF after each header item.
Failure to comply with this will result in strange bugs because the server will most likely ignore part of the headers you specified.

The first line in a request (containing the method, usually a GET or POST) is not a header and cannot be replaced using this option.
Only the lines following the request-line are headers.
Adding this method line in this list of headers will only cause your request to send an invalid header.
Use CURLOPT_CUSTOMREQUEST to change the method.

When this option is passed to curl_easy_setopt, libcurl will not copy the entire list so you must keep it around until you no longer use this handle for a transfer before you call curl_slist_free_all on the list.

Pass a NULL to this option to reset back to no custom headers.

The most commonly replaced headers have "shortcuts" in the options CURLOPT_COOKIE, CURLOPT_USERAGENT and CURLOPT_REFERER. We recommend using those.

There is an alternative option that sets or replaces headers only for requests that are sent with CONNECT to a proxy: CURLOPT_PROXYHEADER.
Use CURLOPT_HEADEROPT to control the behavior.

Security concerns

By default, this option makes libcurl send the given headers in all HTTP requests done by this handle.
You should therefore use this option with caution if you for example connect to the remote site using a proxy and a CONNECT request,
you should to consider if that proxy is supposed to also get the headers.
They may be private or otherwise sensitive to leak.

Use CURLOPT_HEADEROPT to make the headers only get sent to where you intend them to get sent.

Default: NULL

Protocols: HTTP

Example:
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com")
atom headers = NULL
headers = curl_slist_append(headers, "Shoesize: 10")
headers = curl_slist_append(headers, "Accept:")
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers)

curl_easy_perform(curl)
 
/* always cleanup */
curl_easy_cleanup(curl)
curl_slist_free_all(headers)

Availability: As long as HTTP is enabled

Return value: Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.

See also: CURLOPT_CUSTOMREQUEST, CURLOPT_HEADEROPT, CURLOPT_PROXYHEADER, CURLOPT_HEADER
CURLOPT_HEADEROPT Control custom headers. See CURLOPT_HEADEROPT
CURLOPT_PROXYHEADER Custom HTTP headers sent to proxy. See CURLOPT_PROXYHEADER
CURLOPT_HTTP200ALIASES Alternative versions of 200 OK. See CURLOPT_HTTP200ALIASES
CURLOPT_COOKIE Cookie(s) to send. See CURLOPT_COOKIE
CURLOPT_COOKIEFILE File name to read cookies from.

Synopsis: curl_easy_setopt(curl, CURLOPT_COOKIEFILE, string filename)

Specify the file name of your file holding cookie data to read.
The cookie data can be in either the old Netscape / Mozilla cookie data format or just regular HTTP headers (Set-Cookie style) dumped to a file.

It also enables the cookie engine, making libcurl parse and send cookies on subsequent requests with this handle.

Given an empty or non-existing file or by passing the empty string ("") to this option, you can enable the cookie engine without reading any initial cookies.

This option only reads cookies. To make libcurl write cookies to file, see CURLOPT_COOKIEJAR.

Exercise caution if you are using this option and multiple transfers may occur.
If you use the Set-Cookie format and don’t specify a domain then the cookie is sent for any domain (even after redirects are followed) and cannot be modified by a server-set cookie.
If a server sets a cookie of the same name then both will be sent on a future transfer to that server, likely not what you intended.
To address these issues set a domain in Set-Cookie (doing that will include sub-domains) or use the Netscape format.

If you use this option multiple times, you just add more files to read. Subsequent files will add more cookies.

The application does not have to keep the string around after setting this option.

Default: NULL

Protocols: HTTP

Example
include builtins/libcurl.e
 
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/foo.bin")

-- get cookies from an existing file
curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "/tmp/cookies.txt")

object ret = curl_easy_perform(curl)
curl_easy_cleanup(curl)

Availability: As long as HTTP is supported

Return value: Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.

See also: CURLOPT_COOKIE, CURLOPT_COOKIEJAR
CURLOPT_COOKIEJAR File name to write cookies to.

Synopsis: curl_easy_setopt(curl, CURLOPT_COOKIEJAR, string filename)

This will make libcurl write all internally known cookies to the specified file when curl_easy_cleanup is called.
If no cookies are known, no file will be created.
Specify "-" as filename to instead have the cookies written to stdout.
Using this option also enables cookies for this session, so if you for example follow a location it will make matching cookies get sent accordingly.

Note that libcurl doesn’t read any cookies from the cookie jar.
If you want to read cookies from a file, use CURLOPT_COOKIEFILE.

If the cookie jar file can’t be created or written to (when the curl_easy_cleanup is called), libcurl will not and cannot report an error for this.
Using CURLOPT_VERBOSE or CURLOPT_DEBUGFUNCTION will get a warning to display, but that is the only visible feedback you get about this possibly lethal situation.

Since 7.43.0 cookies that were imported in the Set-Cookie format without a domain name are not exported by this option.

The application does not have to keep the string around after setting this option.

Default: NULL

Protocols: HTTP

Example:
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/foo.bin")
 
/* export cookies to this file when closing the handle */
curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "/tmp/cookies.txt");
 
ret = curl_easy_perform(curl)
 
/* close the handle, write the cookies! */
curl_easy_cleanup(curl)

Availability: Along with HTTP

Return value: Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space.

See also: CURLOPT_COOKIEFILE, CURLOPT_COOKIE, CURLOPT_COOKIELIST
CURLOPT_COOKIESESSION Start a new cookie session. See CURLOPT_COOKIESESSION
CURLOPT_COOKIELIST Add to (feed cookie into cookie engine) or manipulate cookies held in memory.

Synopsis: curl_easy_setopt(curl, CURLOPT_COOKIELIST, string cookie)

The cookie can be either a single line in Netscape / Mozilla format or just regular HTTP-style header (Set-Cookie: ...) format.
This will also enable the cookie engine.
This adds that single cookie to the internal cookie store.

Exercise caution if you are using this option and multiple transfers may occur.
If you use the Set-Cookie format and don’t specify a domain then the cookie is sent for any domain (even after redirects are followed) and cannot be modified by a server-set cookie.
If a server sets a cookie of the same name (or maybe you’ve imported one) then both will be sent on a future transfer to that server, likely not what you intended.
To address these issues set a domain in Set-Cookie (doing that will include sub-domains) or use the Netscape format as shown in EXAMPLE.

Additionally, there are commands available that perform actions if you pass in these exact strings:
"ALL" - erases all cookies held in memory
"SESS" - erases all session cookies held in memory
"FLUSH" - writes all known cookies to the file specified by CURLOPT_COOKIEJAR
"RELOAD" - loads all cookies from the files specified by CURLOPT_COOKIEFILE

Default: NULL

Protocols: HTTP

Example:
/* This example shows an inline import of a cookie in Netscape format.
You can set the cookie as HttpOnly to prevent XSS attacks by prepending
#HttpOnly_ to the hostname. That may be useful if the cookie will later
be imported by a browser.
*/
 
string my_cookie = "example.com\tFALSE\t/\tFALSE\t0\tfoo\tbar"
                -- Hostname = example.com,
                -- Include subdomains = FALSE,
                -- Path = \,
                -- Secure = FALSE,
                -- Expiry = 0, (==Session)
                -- Name = foo,
                -- Value = bar

/* my_cookie is imported immediately via CURLOPT_COOKIELIST. */
curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie)
 
/* The list of cookies in cookies.txt will not be imported until right
before a transfer is performed. Cookies in the list that have the same
hostname, path and name as in my_cookie are skipped. That is because
libcurl has already imported my_cookie and it's considered a "live"
cookie. A live cookie won't be replaced by one read from a file.
*/
curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt")   /* import */
 
/* Cookies are exported after curl_easy_cleanup is called. The server
may have added, deleted or modified cookies by then. The cookies that
were skipped on import are not exported.
*/
curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "cookies.txt")  /* export */
 
curl_easy_perform(curl)  /* cookies imported from cookies.txt */
 
curl_easy_cleanup(curl)  /* cookies exported to cookies.txt */

Availability:
ALL was added in 7.14.1
SESS was added in 7.15.4
FLUSH was added in 7.17.1
RELOAD was added in 7.39.0

Return value: Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space.

See also: CURLOPT_COOKIEFILE, CURLOPT_COOKIEJAR, CURLOPT_COOKIE, CURLINFO_COOKIELIST
CURLOPT_HTTPGET Do a HTTP GET request. See CURLOPT_HTTPGET
CURLOPT_REQUEST_TARGET Set the request target. CURLOPT_REQUEST_TARGET
CURLOPT_HTTP_VERSION HTTP version to use. CURLOPT_HTTP_VERSION
CURLOPT_IGNORE_CONTENT_LENGTH Ignore Content-Length. See CURLOPT_IGNORE_CONTENT_LENGTH
CURLOPT_HTTP_CONTENT_DECODING Disable Content decoding. See CURLOPT_HTTP_CONTENT_DECODING
CURLOPT_HTTP_TRANSFER_DECODING Disable Transfer decoding. See CURLOPT_HTTP_TRANSFER_DECODING
CURLOPT_EXPECT_100_TIMEOUT_MS 100-continue timeout. See CURLOPT_EXPECT_100_TIMEOUT_MS
CURLOPT_PIPEWAIT Wait on connection to pipeline on it. See CURLOPT_PIPEWAIT
CURLOPT_STREAM_DEPENDS This HTTP/2 stream depends on another. See CURLOPT_STREAM_DEPENDS
CURLOPT_STREAM_DEPENDS_E This HTTP/2 stream depends on another exclusively. See CURLOPT_STREAM_DEPENDS_E
CURLOPT_STREAM_WEIGHT Set this HTTP/2 stream’s weight. See CURLOPT_STREAM_WEIGHT
SMTP OPTIONS
CURLOPT_MAIL_FROM Address of the sender. See CURLOPT_MAIL_FROM
CURLOPT_MAIL_RCPT Address of the recipients. See CURLOPT_MAIL_RCPT
CURLOPT_MAIL_AUTH Authentication address. See CURLOPT_MAIL_AUTH
TFTP OPTIONS
CURLOPT_TFTP_BLKSIZE TFTP block size. See CURLOPT_TFTP_BLKSIZE
CURLOPT_TFTP_NO_OPTIONS Do not send TFTP options requests. See CURLOPT_TFTP_NO_OPTIONS
FTP OPTIONS
CURLOPT_FTPPORT Use active FTP. See CURLOPT_FTPPORT
CURLOPT_QUOTE Commands to run before transfer. See CURLOPT_QUOTE
CURLOPT_POSTQUOTE Commands to run after transfer. See CURLOPT_POSTQUOTE
CURLOPT_PREQUOTE Commands to run just before transfer. See CURLOPT_PREQUOTE
CURLOPT_APPEND Append to remote file. See CURLOPT_APPEND
CURLOPT_FTP_USE_EPRT Use EPTR. See CURLOPT_FTP_USE_EPRT
CURLOPT_FTP_USE_EPSV Use EPSV. See CURLOPT_FTP_USE_EPSV
CURLOPT_FTP_USE_PRET Use PRET. See CURLOPT_FTP_USE_PRET
CURLOPT_FTP_CREATE_MISSING_DIRS Create missing directories on the remote server. See CURLOPT_FTP_CREATE_MISSING_DIRS
CURLOPT_FTP_RESPONSE_TIMEOUT Timeout for FTP responses. See CURLOPT_FTP_RESPONSE_TIMEOUT
CURLOPT_FTP_ALTERNATIVE_TO_USER Alternative to USER. See CURLOPT_FTP_ALTERNATIVE_TO_USER
CURLOPT_FTP_SKIP_PASV_IP Ignore the IP address in the PASV response. See CURLOPT_FTP_SKIP_PASV_IP
CURLOPT_FTPSSLAUTH Control how to do TLS. See CURLOPT_FTPSSLAUTH
CURLOPT_FTP_SSL_CCC Back to non-TLS again after authentication. See CURLOPT_FTP_SSL_CCC
CURLOPT_FTP_ACCOUNT Send ACCT command. See CURLOPT_FTP_ACCOUNT
CURLOPT_FTP_FILEMETHOD Specify how to reach files. See CURLOPT_FTP_FILEMETHOD
RTSP OPTIONS
CURLOPT_RTSP_REQUEST RTSP request. See CURLOPT_RTSP_REQUEST
CURLOPT_RTSP_SESSION_ID RTSP session-id. See CURLOPT_RTSP_SESSION_ID
CURLOPT_RTSP_STREAM_URI RTSP stream URI. See CURLOPT_RTSP_STREAM_URI
CURLOPT_RTSP_TRANSPORT RTSP Transport: header. See CURLOPT_RTSP_TRANSPORT
CURLOPT_RTSP_CLIENT_CSEQ Client CSEQ number. See CURLOPT_RTSP_CLIENT_CSEQ
CURLOPT_RTSP_SERVER_CSEQ CSEQ number for RTSP Server->Client request. See CURLOPT_RTSP_SERVER_CSEQ
PROTOCOL OPTIONS
CURLOPT_TRANSFERTEXT Use text transfer. See CURLOPT_TRANSFERTEXT
CURLOPT_PROXY_TRANSFER_MODE Add transfer mode to URL over proxy. See CURLOPT_PROXY_TRANSFER_MODE
CURLOPT_CRLF Convert newlines. See CURLOPT_CRLF
CURLOPT_RANGE Range requests. See CURLOPT_RANGE
CURLOPT_RESUME_FROM Resume a transfer. See CURLOPT_RESUME_FROM
CURLOPT_RESUME_FROM_LARGE Resume a transfer. See CURLOPT_RESUME_FROM_LARGE
CURLOPT_CUSTOMREQUEST Custom request/method.

Synopsis: curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, nullable_string request)

When you change the request method by setting CURLOPT_CUSTOMREQUEST to something, you don’t actually change how libcurl behaves or acts in regards to the particular request method, it will only change the actual string sent in the request.

Restore to the internal default by setting this to NULL.

This option can be used to specify the request:

HTTP
Instead of GET or HEAD when performing HTTP based requests. This is particularly useful, for example, for performing a HTTP DELETE request.

For example:
When you tell libcurl to do a HEAD request, but then specify a GET though a custom request libcurl will still act as if it sent a HEAD.
To switch to a proper HEAD use CURLOPT_NOBODY, to switch to a proper POST use CURLOPT_POST or CURLOPT_POSTFIELDS and to switch to a proper GET use CURLOPT_HTTPGET.

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 CURLOPT_POST and CURLOPT_POSTFIELDS to set POST data.
Use CURLOPT_HTTPHEADER to replace or extend the set of headers sent by libcurl.
Use CURLOPT_HTTP_VERSION to change HTTP version.

FTP
Instead of LIST and NLST when performing FTP directory listings.

IMAP
Instead of LIST when issuing IMAP based requests.

POP3
Instead of LIST and RETR when issuing POP3 based requests.

For example:
When you tell libcurl to use a custom request it will behave like a LIST or RETR command was sent where it expects data to be returned by the server.
As such CURLOPT_NOBODY should be used when specifying commands such as DELE and NOOP for example.

SMTP
Instead of a HELP or VRFY when issuing SMTP based requests.

For example:
Normally a multiline response is returned which can be used, in conjunction with CURLOPT_MAIL_RCPT, to specify an EXPN request.
If the CURLOPT_NOBODY option is specified then the request can be used to issue NOOP and RSET commands.

The application does not have to keep the string around after setting this option.

Default: NULL

Protocols: HTTP, FTP, IMAP, POP3 and SMTP

Example:
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/foo.bin")
/* DELETE the given path */
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE");
ret = curl_easy_perform(curl)
curl_easy_cleanup(curl)

Availability: IMAP is supported since 7.30.0, POP3 since 7.26.0 and SMTP since 7.34.0.

Return value: Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space.

See also: CURLOPT_HTTPHEADER, CURLOPT_NOBODY, CURLOPT_REQUEST_TARGET
CURLOPT_FILETIME Request file modification date and time. See CURLOPT_FILETIME
CURLOPT_DIRLISTONLY List only. See CURLOPT_DIRLISTONLY
CURLOPT_NOBODY Do not get the body contents. See CURLOPT_NOBODY
CURLOPT_INFILESIZE Size of file to send. CURLOPT_INFILESIZE
CURLOPT_INFILESIZE_LARGE Size of file to send. CURLOPT_INFILESIZE_LARGE
CURLOPT_UPLOAD Upload data. See CURLOPT_UPLOAD
CURLOPT_MIMEPOST Post/send MIME data. See CURLOPT_MIMEPOST
CURLOPT_MAXFILESIZE Maximum file size to get. See CURLOPT_MAXFILESIZE
CURLOPT_MAXFILESIZE_LARGE Maximum file size to get. See CURLOPT_MAXFILESIZE_LARGE
CURLOPT_TIMECONDITION Make a time conditional request. See CURLOPT_TIMECONDITION
CURLOPT_TIMEVALUE Time value for the time conditional request. See CURLOPT_TIMEVALUE
CONNECTION OPTIONS
CURLOPT_TIMEOUT Timeout for the entire request. See CURLOPT_TIMEOUT
CURLOPT_TIMEOUT_MS Millisecond timeout for the entire request. See CURLOPT_TIMEOUT_MS
CURLOPT_LOW_SPEED_LIMIT Low speed limit to abort transfer. See CURLOPT_LOW_SPEED_LIMIT
CURLOPT_LOW_SPEED_TIME Time to be below the speed to trigger low speed abort. See CURLOPT_LOW_SPEED_TIME
CURLOPT_MAX_SEND_SPEED_LARGE Cap the upload speed to this. See CURLOPT_MAX_SEND_SPEED_LARGE
CURLOPT_MAX_RECV_SPEED_LARGE Cap the download speed to this. See CURLOPT_MAX_RECV_SPEED_LARGE
CURLOPT_MAXCONNECTS Maximum number of connections in the connection pool. See CURLOPT_MAXCONNECTS
CURLOPT_FRESH_CONNECT Use a new connection. CURLOPT_FRESH_CONNECT
CURLOPT_FORBID_REUSE Prevent subsequent connections from re-using this. See CURLOPT_FORBID_REUSE
CURLOPT_CONNECTTIMEOUT Timeout for the connection phase. See CURLOPT_CONNECTTIMEOUT
CURLOPT_CONNECTTIMEOUT_MS Millisecond timeout for the connection phase. See CURLOPT_CONNECTTIMEOUT_MS
CURLOPT_IPRESOLVE IP version to resolve to. See CURLOPT_IPRESOLVE
CURLOPT_CONNECT_ONLY Only connect, nothing else (stop when connected to target server).

Synopsis: curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, bool only)

If the parameter is true(1), it tells the library to perform all the required proxy authentication and connection setup, but no data transfer, and then return.

The option can be used to simply test a connection to a server, but is more useful when used with the CURLINFO_ACTIVESOCKET option to curl_easy_getinfo as the library can set up the connection and then the application can obtain the most recently used socket for special data transfers.

Default: false(0)

Protocols: HTTP, SMTP, POP3 and IMAP

Example
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com")
curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, true)
CURLcode ret = curl_easy_perform(curl);
if ret=CURLE_OK then
    /* only connected! */
end if

Availability: Added in 7.15.2

Return value: Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.

See also: CURLOPT_VERBOSE, CURLOPT_HTTPPROXYTUNNEL, curl_easy_recv, curl_easy_send
CURLOPT_USE_SSL Use TLS/SSL. See CURLOPT_USE_SSL
CURLOPT_RESOLVE Provide fixed/fake custom host name to IP address resolves.

Synopsis: curl_easy_setopt(curl, CURLOPT_RESOLVE, atom hosts)

Pass an slist (linked list of strings) with host name resolve information to use for requests with this handle.
The linked list should be a fully valid list of struct curl_slist structs properly filled in.
Use curl_slist_append to create the list and curl_slist_free_all to clean up an entire list.

Each single name resolve string should be written using the format HOST:PORT:ADDRESS where
HOST is the name libcurl will try to resolve,
PORT is the port number of the service where libcurl wants to connect to the HOST and
ADDRESS is the numerical IP address.
If libcurl is built to support IPv6, ADDRESS can of course be either IPv4 or IPv6 style addressing.

This option effectively pre-populates the DNS cache with entries for the host+port pair so redirects and everything
that operations against the HOST+PORT will instead use your provided ADDRESS.
Addresses set with CURLOPT_RESOLVE will not time-out from the DNS cache like ordinary entries.

The provided ADDRESS set by this option will be used even if CURLOPT_IPRESOLVE is set to make libcurl use another IP version.

Remove names from the DNS cache again, to stop providing these fake resolves, by including a string in the linked list that uses the format "-HOST:PORT".
The host name must be prefixed with a dash, and the host name and port number must exactly match what was already added previously.

Support for providing the ADDRESS within [brackets] was added in 7.57.0.

Default: NULL

Protocols: All

Example: (see also demo/libcurl/read_cookies.exw)
atom hosts = NULL
hosts = curl_slist_append(hosts, "example.com:80:127.0.0.1")
 
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_RESOLVE, hosts)
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com")
 
/* always cleanup */
curl_easy_cleanup(curl)

curl_slist_free_all(hosts)

Availability: Added in 7.21.3. Removal support added in 7.42.0.

Return value: Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.

See also: CURLOPT_IPRESOLVE, CURLOPT_DNS_CACHE_TIMEOUT, CURLOPT_CONNECT_TO
CURLOPT_DNS_INTERFACE Bind name resolves to this interface. See CURLOPT_DNS_INTERFACE
CURLOPT_DNS_LOCAL_IP4 Bind name resolves to this IP4 address. See CURLOPT_DNS_LOCAL_IP4
CURLOPT_DNS_LOCAL_IP6 Bind name resolves to this IP6 address. See CURLOPT_DNS_LOCAL_IP6
CURLOPT_DNS_SERVERS Preferred DNS servers. See CURLOPT_DNS_SERVERS
CURLOPT_ACCEPTTIMEOUT_MS Timeout for waiting for the server’s connect back to be accepted. See CURLOPT_ACCEPTTIMEOUT_MS
SSL and SECURITY OPTIONS
CURLOPT_SSLCERT Client cert. See CURLOPT_SSLCERT
CURLOPT_PROXY_SSLCERT Proxy client cert. See CURLOPT_PROXY_SSLCERT
CURLOPT_SSLCERTTYPE Client cert type. See CURLOPT_SSLCERTTYPE
CURLOPT_PROXY_SSLCERTTYPE Proxy client cert type. See CURLOPT_PROXY_SSLCERTTYPE
CURLOPT_SSLKEY Client key. See CURLOPT_SSLKEY
CURLOPT_PROXY_SSLKEY Proxy client key. See CURLOPT_PROXY_SSLKEY
CURLOPT_SSLKEYTYPE Client key type. See CURLOPT_SSLKEYTYPE
CURLOPT_PROXY_SSLKEYTYPE Proxy client key type. See CURLOPT_PROXY_SSLKEYTYPE
CURLOPT_KEYPASSWD Client key password. See CURLOPT_KEYPASSWD
CURLOPT_PROXY_KEYPASSWD Proxy client key password. See CURLOPT_PROXY_KEYPASSWD
CURLOPT_SSL_ENABLE_ALPN Enable use of ALPN. See CURLOPT_SSL_ENABLE_ALPN
CURLOPT_SSL_ENABLE_NPN Enable use of NPN. See CURLOPT_SSL_ENABLE_NPN
CURLOPT_SSLENGINE Use identifier with SSL engine. See CURLOPT_SSLENGINE
CURLOPT_SSLENGINE_DEFAULT Default SSL engine. See CURLOPT_SSLENGINE_DEFAULT
CURLOPT_SSL_FALSESTART Enable TLS False Start. See CURLOPT_SSL_FALSESTART
CURLOPT_SSLVERSION SSL version to use. See CURLOPT_SSLVERSION
CURLOPT_PROXY_SSLVERSION Proxy SSL version to use. See CURLOPT_PROXY_SSLVERSION
CURLOPT_SSL_VERIFYHOST Verify the host name in the SSL certificate.

Synopsis: curl_easy_setopt(atom curl, CURLOPT_SSL_VERIFYHOST, bool verify)

This option determines whether libcurl verifies that the server certificate is for the server it is known as.
(aside: an internal mapping of 1:=2 occurs automatically, to cover some deprecated debug option; the value of 2 is also accepted, and treated as true)

When negotiating TLS and SSL connections, the server sends a certificate indicating its identity.

When true, that certificate must indicate that the server is the server to which you meant to connect, or the connection fails.
Simply put, it means it has to have the same name in the certificate as is in the URL you operate against.

Curl considers the server the intended one when the Common Name field or a Subject Alternate Name field in the certificate matches the host name in the URL to which you told Curl to connect.

When false, the connection succeeds regardless of the names in the certificate. Use that ability with caution!

The default value for this option is true.

This option controls checking the server’s certificate’s claimed identity.
The server could be lying.
To control lying, see CURLOPT_SSL_VERIFYPEER.

Limitations:
DarwinSSL: If verify value is 0, then SNI is also disabled. SNI is a TLS extension that sends the hostname to the server.
The server may use that information to do such things as sending back a specific certificate for the hostname, or forwarding the request to a specific origin server. Some hostnames may be inaccessible if SNI is not sent.
NSS: If CURLOPT_SSL_VERIFYPEER is zero, CURLOPT_SSL_VERIFYHOST is also set to zero and cannot be overridden.

Protocols: All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.

Availability: If built TLS enabled.

Return value: Returns CURLE_OK if TLS is supported, and CURLE_UNKNOWN_OPTION if not.

See also: CURLOPT_SSL_VERIFYPEER, CURLOPT_CAINFO
CURLOPT_PROXY_SSL_VERIFYHOST Verify the host name in the proxy SSL certificate. See CURLOPT_PROXY_SSL_VERIFYHOST
CURLOPT_SSL_VERIFYPEER Verify the SSL certificate.

Synopsis: curl_easy_setopt(atom curl, CURLOPT_SSL_VERIFYPEER, bool verify)

Pass true(1) or false(0) as parameter to enable or disable.

This option determines whether curl verifies the authenticity of the peer’s certificate.
A value of 1 means curl verifies; 0 (zero) means it does not.

When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity.
Curl verifies whether the certificate is authentic, i.e. that you can trust that the server is who the certificate says it is.
This trust is based on a chain of digital signatures, rooted in certification authority (CA) certificates you supply.
curl uses a default bundle of CA certificates (the path for that is determined at build time) and you can specify alternate certificates with the CURLOPT_CAINFO option or the CURLOPT_CAPATH option.

When CURLOPT_SSL_VERIFYPEER is enabled, and the verification fails to prove that the certificate is authentic, the connection fails.
When the option is zero, the peer certificate verification succeeds regardless.

Authenticating the certificate is not enough to be sure about the server.
You typically also want to ensure that the server is the server you mean to be talking to.
Use CURLOPT_SSL_VERIFYHOST for that.
The check that the host name in the certificate is valid for the host name you are connecting to is done independently of the CURLOPT_SSL_VERIFYPEER option.

WARNING: disabling verification of the certificate allows bad guys to man-in-the-middle the communication without you knowing it.
Disabling verification makes the communication insecure.
Just having encryption on a transfer is not enough as you cannot be sure that you are communicating with the correct end-point.

Default: By default, curl assumes a value of 1.

Protocols: All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.

Availability: If built TLS enabled.

Return value: Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.

See also: CURLOPT_SSL_VERIFYHOST, CURLOPT_PROXY_SSL_VERIFYPEER, CURLOPT_PROXY_SSL_VERIFYHOST
CURLOPT_PROXY_SSL_VERIFYPEER Verify the proxy SSL certificate. See CURLOPT_PROXY_SSL_VERIFYPEER
CURLOPT_SSL_VERIFYSTATUS Verify the SSL certificate’s status. See CURLOPT_SSL_VERIFYSTATUS
CURLOPT_CAINFO CA cert bundle. See CURLOPT_CAINFO
CURLOPT_PROXY_CAINFO Proxy CA cert bundle. See CURLOPT_PROXY_CAINFO
CURLOPT_ISSUERCERT Issuer certificate. See CURLOPT_ISSUERCERT
CURLOPT_CAPATH Path to CA cert bundle. See CURLOPT_CAPATH
CURLOPT_PROXY_CAPATH Path to proxy CA cert bundle. See CURLOPT_PROXY_CAPATH
CURLOPT_CRLFILE Certificate Revocation List. See CURLOPT_CRLFILE
CURLOPT_PROXY_CRLFILE Proxy Certificate Revocation List. See CURLOPT_PROXY_CRLFILE
CURLOPT_CERTINFO Extract/request SSL certificate information.

Synopsis: curl_easy_setopt(atom curl, CURLOPT_CERTINFO, bool certinfo)

Pass true (1) to enable libcurl’s certificate chain info gatherer.
With this enabled, libcurl will extract lots of information and data about the certificates in the certificate chain used in the SSL connection.
This data may then be retrieved after a transfer using curl_easy_getinfo and its option CURLINFO_CERTINFO.

Default: false (0)

Protocols: All TLS-based

Availability: This option is supported by the OpenSSL, GnuTLS, NSS and GSKit backends.

Return value: Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.

See also: CURLOPT_CAINFO, CURLOPT_SSL_VERIFYPEER
CURLOPT_PINNEDPUBLICKEY Set pinned SSL public key . See CURLOPT_PINNEDPUBLICKEY
CURLOPT_PROXY_PINNEDPUBLICKEY Set the proxy’s pinned SSL public key. See CURLOPT_PROXY_PINNEDPUBLICKEY
CURLOPT_RANDOM_FILE Provide source for entropy random data. See CURLOPT_RANDOM_FILE
CURLOPT_EGDSOCKET Identify EGD socket for entropy. See CURLOPT_EGDSOCKET
CURLOPT_SSL_CIPHER_LIST Ciphers to use. See CURLOPT_SSL_CIPHER_LIST
CURLOPT_PROXY_SSL_CIPHER_LIST Proxy ciphers to use. See CURLOPT_PROXY_SSL_CIPHER_LIST
CURLOPT_SSL_SESSIONID_CACHE Disable SSL session-id cache. See CURLOPT_SSL_SESSIONID_CACHE
CURLOPT_SSL_OPTIONS Control SSL behavior. See CURLOPT_SSL_OPTIONS
CURLOPT_PROXY_SSL_OPTIONS Control proxy SSL behavior. See CURLOPT_PROXY_SSL_OPTIONS
CURLOPT_KRBLEVEL Kerberos security level. See CURLOPT_KRBLEVEL
CURLOPT_GSSAPI_DELEGATION Disable GSS-API delegation. See CURLOPT_GSSAPI_DELEGATION
SSH OPTIONS
CURLOPT_SSH_AUTH_TYPES SSH authentication types. See CURLOPT_SSH_AUTH_TYPES
CURLOPT_SSH_COMPRESSION Enable SSH compression. See CURLOPT_SSH_COMPRESSION
CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 MD5 of host’s public key. See CURLOPT_SSH_HOST_PUBLIC_KEY_MD5
CURLOPT_SSH_PUBLIC_KEYFILE File name of public key. See CURLOPT_SSH_PUBLIC_KEYFILE
CURLOPT_SSH_PRIVATE_KEYFILE File name of private key. See CURLOPT_SSH_PRIVATE_KEYFILE
CURLOPT_SSH_KNOWNHOSTS File name with known hosts. See CURLOPT_SSH_KNOWNHOSTS
CURLOPT_SSH_KEYFUNCTION Callback for known hosts handling. See CURLOPT_SSH_KEYFUNCTION
CURLOPT_SSH_KEYDATA Custom pointer to pass to ssh key callback. See CURLOPT_SSH_KEYDATA
OTHER OPTIONS
CURLOPT_PRIVATE Private pointer to store. See CURLOPT_PRIVATE
CURLOPT_SHARE Share object to use. See CURLOPT_SHARE
CURLOPT_NEW_FILE_PERMS Mode for creating new remote files. See CURLOPT_NEW_FILE_PERMS
CURLOPT_NEW_DIRECTORY_PERMS Mode for creating new remote directories. See CURLOPT_NEW_DIRECTORY_PERMS
TELNET OPTIONS
CURLOPT_TELNETOPTIONS TELNET options. See CURLOPT_TELNETOPTIONS
See Also: SEE ALSO , curl_multi_strerror, curl_share_strerror, , , CURLOPT_DEBUGFUNCTION curl_easy_strerror, CURLOPT_ERRORBUFFER, CURLOPT_VERBOSE, x