curl

Properties

version ⇢ string:

The libcurl version.

Functions

get_time(date_string)

Returns the number of seconds since the Epoch, January 1st 1970 00:00:00 in the UTC time zone, for the date and time that the date_string parameter specifies.

PARSING DATES AND TIMES

A "date" is a string containing several items separated by whitespace. The order of the items is immaterial. A date string may contain many flavors of items:

Calendar date Can be specified several ways. Month names can only be three-letter english abbreviations, numbers can be zero-prefixed and the year may use 2 or 4 digits.

Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6.
Time of the day This string specifies the time on a given day. You must specify it with 6 digits with two colons: HH:MM:SS. To not include the time in a date string, will make the function assume 00:00:00.

Example: 18:19:21.
Time zone Specifies international time zone. There are a few acronyms supported, but in general you should instead use the specific relative time compared to UTC. Supported formats include: -1200, MST, +0100.
Day of the week items Specifies a day of the week. Days of the week may be spelled out in full (using english): Sunday, Monday, etc or they may be abbreviated to their first three letters. This is usually not info that adds anything.
Pure numbers If a decimal number of the form YYYYMMDD appears, then YYYY is read as the year, MM as the month number and DD as the day of the month, for the specified calendar date.

EXAMPLES

Sun, 06 Nov 1994 08:49:37 GMT
Sunday, 06-Nov-94 08:49:37 GMT
Sun Nov  6 08:49:37 1994
06 Nov 1994 08:49:37 GMT
06-Nov-94 08:49:37 GMT
Nov  6 08:49:37 1994
06 Nov 1994 08:49:37
06-Nov-94 08:49:37
1994 Nov 6 08:49:37
GMT 08:49:37 06-Nov-94 Sunday
94 6 Nov 08:49:37
1994 Nov 6
06-Nov-94
Sun Nov 6 94
1994.Nov.6
Sun/Nov/6/94/GMT
Sun, 06 Nov 1994 08:49:37 CET
06 Nov 1994 08:49:37 EST
Sun, 12 Sep 2004 15:05:58 -0700
Sat, 11 Sep 2004 21:32:11 +0200
20040912 15:05:58 -0700
20040911 +0200

STANDARDS

This parser was written to handle date formats specified in RFC 822 (including the update in RFC 1123) using time zone name or time zone delta and RFC 850 (obsoleted by RFC 1036) and ANSI C's asctime() format. These formats are the only ones RFC 7231 says HTTP applications may use.

@static

Parameters

string date_string

Returns

number

Classes

class Info

cURL request and response informations for get_info()

Fields

EFFECTIVE_URL ⇢ static:

Gets the last used effective URL. If follow redirects is enabled, it may very well not be the same value you set in the original request.
RESPONSE_CODE ⇢ static:

The last received HTTP, FTP or SMTP response code. The value will be zero if no server response code has been received.
TOTAL_TIME ⇢ static:

The total time in seconds for the previous transfer, including name resolving, TCP connect etc. The value represents the time in seconds, including fractions.
NAMELOOKUP_TIME ⇢ static:

The total time in seconds from the start until the name resolving was completed.
CONNECT_TIME ⇢ static:

The total time in seconds from the start until the connection to the remote host (or proxy) was completed.
PRETRANSFER_TIME ⇢ static:

The time, in seconds, it took from the start until a file transfer is just about to begin.

This time-stamp includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. It includes the sending of the protocol- specific protocol instructions that triggers a transfer.

SIZE_UPLOAD ⇢ static:

The total amount of bytes that were uploaded.
SIZE_DOWNLOAD ⇢ static:

The total amount of bytes that were downloaded. The amount is only for the latest transfer and will be reset again for each new transfer. This counts actual payload data, what's also commonly called body. All meta and header data are excluded and will not be counted in this number.
SPEED_DOWNLOAD ⇢ static:

The average download speed that curl measured for the complete download. Measured in bytes/second.
SPEED_UPLOAD ⇢ static:

The average upload speed that curl measured for the complete upload. Measured in bytes/second.
HEADER_SIZE ⇢ static:

The total size of all the headers received. Measured in number of bytes.
REQUEST_SIZE ⇢ static:

The total size of the issued requests. This is so far only for HTTP requests.
SSL_VERIFYRESULT ⇢ static:

The result of the server SSL certificate verification that was requested (using the Options.SSL_VERIFYPEER option).
FILETIME ⇢ static:

The remote time of the retrieved document (in number of seconds since 1 jan 1970 in the GMT/UTC time zone). If you get -1, it can be because of many reasons (it might be unknown, the server might hide it or the server doesn't support the command that tells document time etc) and the time of the document is unknown.

You MUST to collect this information before the transfer is made, by using the Options.FILETIME option to set_option() or you will unconditionally get a -1 back.

CONTENT_LENGTH_DOWNLOAD ⇢ static:

The content-length of the download. This is the value read from the Content-Length: field. It is -1 if the size isn't known.
CONTENT_LENGTH_UPLOAD ⇢ static:

The content-length of the upload. It is -1 if the size isn't known.
STARTTRANSFER_TIME ⇢ static:

The time, in seconds, it took from the start until the first byte is received by curl. This includes PRETRANSFER_TIME and also the time the server needs to calculate the result.
CONTENT_TYPE ⇢ static:

The content-type of the downloaded object. This is the value read from the Content-Type: field. If you get nil, it means that the server didn't send a valid Content-Type header or that the protocol used doesn't support this.
REDIRECT_TIME ⇢ static:

The total time, in seconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started.
REDIRECT_COUNT ⇢ static:

The total number of redirections that were actually followed.
HTTP_CONNECTCODE ⇢ static:

The last received HTTP proxy response code to a CONNECT request. The returned value will be zero if no such response code was available.
HTTPAUTH_AVAIL ⇢ static:

A bitmask indicating the authentication method(s) available according to the previous response.
PROXYAUTH_AVAIL ⇢ static:

A bitmask indicating the authentication method(s) available according to the previous response.
OS_ERRNO ⇢ static:

The errno variable from a connect failure. Note that the value is only set on failure, it is not reset upon a successful operation. The number is OS and system specific.
NUM_CONNECTS ⇢ static:

How many new connections curl had to create to achieve the previous transfer (only the successful connects are counted). Combined with REDIRECT_COUNT you are able to know how many times curl successfully reused existing connection(s) or not.
COOKIELIST ⇢ static:

A list of all cookies curl knows (expired ones, too). If there are no cookies, an empty list is returned.

Cookies that were imported in the Set-Cookie format without a domain name may not exported by this option.

FTP_ENTRY_PATH ⇢ static:

A string holding the path of the entry path. That is the initial path curl ended up in when logging on to the remote FTP server. This value is nil if something is wrong.
REDIRECT_URL ⇢ static:

The URL a redirect would take you to if you would enable FOLLOWLOCATION. This can come very handy if you think using the built-in curl redirect logic isn't good enough for you but you would still prefer to avoid implementing all the magic of figuring out the new URL.
PRIMARY_IP ⇢ static:

A string holding the IP address of the most recent connection done with this curl handle.
APPCONNECT_TIME ⇢ static:

The time, in seconds, it took from the start until the SSL/SSH connect/handshake to the remote host was completed. This time is most often very near to the PRETRANSFER_TIME time, except for cases such as HTTP pipelining where the pretransfer time can be delayed due to waits in line for the pipeline and more.
CERTINFO ⇢ static:

Lists with info about the certificate chain, assuming you had Options.CERTINFO enabled when the request was made. Information in each entry of the list is provided in a series of data in the format "name:content" where the content is for the specific named data.
CONDITION_UNMET ⇢ static:

The number 1 if the condition provided in the previous request didn't match (see Options.TIMECONDITION). Alas, if this returns a 1 you know that the reason you didn't get data in return is because it didn't fulfill the condition. This value will be zero if the condition was met. This can also return 1 if the server responded with a 304 HTTP status code, for example after sending a custom "If-Match-" header. @static
RTSP_SESSION_ID ⇢ static:

A string holding the most recent RTSP Session ID.

Applications wishing to resume an RTSP session on another connection should retrieve this info before closing the active connection.

RTSP_CLIENT_CSEQ ⇢ static:

The next CSeq that will be used by the application.
RTSP_SERVER_CSEQ ⇢ static:

The next CSeq that is expected by the application.

Applications wishing to resume an RTSP session on another connection should retrieve this info before closing the active connection.

RTSP_CSEQ_RECV ⇢ static:

The most recently received CSeq from the server.
PRIMARY_PORT ⇢ static:

The destination port of the most recent connection done with the curl instance.
LOCAL_IP ⇢ static:

A string holding the IP address of the local end of most recent connection done with the curl instance.
LOCAL_PORT ⇢ static:

The local port number of the most recent connection done with the curl instance.
HTTP_VERSION ⇢ static:

The HTTP version used in the last http connection.
PROXY_SSL_VERIFYRESULT ⇢ static:

The result of the certificate verification that was requested (using the Options.PROXY_SSL_VERIFYPEER option.
PROTOCOL ⇢ static:

The protocol used in the last request.
SCHEME ⇢ static:

A string holding the URL scheme used for the most recent connection done with this curl instance.
TOTAL_TIME_T ⇢ static:

The total time in microseconds for the previous transfer, including name resolving, TCP connect etc.
NAMELOOKUP_TIME_T ⇢ static:

The total time in microseconds from the start until the name resolving was completed.
CONNECT_TIME_T ⇢ static:

The total time in microseconds from the start until the connection to the remote host (or proxy) was completed.
PRETRANSFER_TIME_T ⇢ static:

The total time in microseconds from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. It does not involve the sending of the protocol- specific request that triggers a transfer.
STARTTRANSFER_TIME_T ⇢ static:

The total time in microseconds from the start until the first byte is received by curl. This includes PRETRANSFER_TIME_T and also the time the server needs to calculate the result.
REDIRECT_TIME_T ⇢ static:

The total time in microseconds it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started. It contains the complete execution time for multiple redirections.
APPCONNECT_TIME_T ⇢ static:

The total time in microseconds from the start until the SSL/SSH connect/handshake to the remote host was completed. This time is most often very near to the PRETRANSFER_TIME_T time, except for cases such as HTTP pipelining where the pretransfer time can be delayed due to waits in line for the pipeline and more.
RETRY_AFTER ⇢ static:

The number of seconds the HTTP server suggests the client should wait until the next request is issued.

While the HTTP header might contain a fixed date string, the RETRY_AFTER will always return number of seconds to wait - or zero if there was no header or the header couldn't be parsed.

class CurlMime

cURL Mime object for multipart-data forms and POST requests.

Methods

CurlMime(curl) ⇢ Constructor

@pram {Curl} curl

add(name, value)

Adds a new mime part with the given name and value.

Parameters

string name
any value

Returns

bool

add_as(value, type)

Adds a new mime part with the given data and type.

Parameters

any value
string type

Returns

bool

add_data(data)

Adds a new mime part with the given data.

Parameters

any data

Returns

bool

add_file(name, value)

Adds a new mime part with the given name and file.

Parameters

string name
string|instance value

Returns

bool

add_mime(mime, type)

Adds a new mime subpart with the given mime.

Parameters

CurlMime mime
string type

Returns

bool

set_encoding(encoding)

Sets the encoding with which the mime will be transfered.

Parameters

string encoding

get_pointer()

Returns the raw pointer object to the underlying libcurl mime implementation.

class CurlList

cURL list interface.

Methods

CurlList(items)

@constrctor

Parameters

list[string] items

close()

Close and disposes the pointer to the list

get_pointer()

Returns the raw pointer object to the underlying libcurl list implementation.

class Curl

cURL class

Methods

Curl() ⇢ Constructor

set_option(option, value)

This function is used to tell curl how to behave. By setting the appropriate options, the application can change curl's behavior.
All options are set with an option followed by a parameter. That parameter can be a number, boolean, string, or an object pointer, depending on what the specific option expects. Read this cURL manual carefully as bad input values may cause curl to behave badly! You can only set one option in each function call. A typical application uses many set_option() calls in the setup phase.

Options set with this function call are valid for all forthcoming transfers performed using this instance. The options are not in any way reset between transfers, so if you want subsequent transfers with different options, you must change them between the transfers. You can optionally reset all options back to internal default with reset().

Parameters

Option option
any value

Returns

boolean

Notes

Strings passed to curl as arguments, must not exceed 8MB in size.
The order in which the options are set does not matter.

get_info(info)

Requests internal information from the curl session with this function. Use this function AFTER performing a transfer if you want to get transfer related data.

Parameters

Info info

Returns

string|number|list

escape(str)

This function converts the given input string to a URL encoded string and returns that as a new allocated string. All input characters that are not a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" version (%NN where NN is a two-digit hexadecimal number).

Parameters

string str

Returns

string

Notes

This function does not accept a strings longer than 8MB.

unescape(str)

This function converts the given URL encoded input string to a "plain string" and returns that in an allocated memory area. All input characters that are URL encoded (%XX where XX is a two-digit hexadecimal number) are converted to their decoded versions.

Parameters

string str

Returns

string

send()

Performs the entire request in a blocking manner and returns when done, or if it failed. It returns a dictionary containing the headers and body key.

You must never call this function simultaneously from two places using the same instance. Let the function return first before invoking it another time.

Returns

dict

reset()

Re-initializes the instace to the default values. This puts back the instance to the same state as it was in when it was just created.

It keeps live connections, the Session ID cache, the DNS cache, the cookies , the shares or the alt-svc cache.

close()

Closes the current Curl instance.

This might close all connections this instance has used and possibly has kept open until now - unless it was attached to a multi handle while doing the transfers. Don't call this function if you intend to transfer more files, re-using Curl instances is a key to good performance.

Notes

Calling a function on the instance after this function has been called is illegal

get_pointer()

Returns the raw pointer object to the underlying libcurl.

class Auth

Auth values for Options.HTTPAUTH and Options.PROXYAUTH

Fields

NONE ⇢ static:

No HTTP authentication
BASIC ⇢ static:

HTTP Basic authentication (default)
DIGEST ⇢ static:

HTTP Digest authentication
NEGOTIATE ⇢ static:

HTTP Negotiate (SPNEGO) authentication
GSSNEGOTIATE ⇢ static:

Alias for CURLAUTH_NEGOTIATE (deprecated)
NTLM ⇢ static:

HTTP NTLM authentication
DIGEST_IE ⇢ static:

HTTP Digest authentication with IE flavour
NTLM_WB ⇢ static:

HTTP NTLM authentication delegated to winbind helper
BEARER ⇢ static:

HTTP Bearer token authentication
ONLY ⇢ static:

Use together with a single other type to force no authentication or just that single type.
ANY ⇢ static:

All fine types set
ANYSAFE ⇢ static:

All fine types except Basic
SSH_ANY ⇢ static:

All types of SSH authentication supported by the server
SSH_NONE ⇢ static:

No SSH allowed
SSH_PUBLICKEY ⇢ static:

Public/private key files for SSH authentication.
SSH_PASSWORD ⇢ static:

Password for SSH authentication.
SSH_HOST ⇢ static:

Host key files for SSH authentication.
SSH_KEYBOARD ⇢ static:

Keyboard interactive SSH authentication.
SSH_AGENT ⇢ static:

Agent (ssh-agent, pageant, etc.) for SSH authentication.
SSH_GSSAPI ⇢ static:

gssapi (kerberos, etc.) for SSH authentication.
SSH_DEFAULT ⇢ static:

The default SSH authentication (same as ANY).

class UseSSL

cURL request options for set_option()

Fields

NONE ⇢ static:

Do not attempt to use SSL.
TRY ⇢ static:

Try using SSL, proceed anyway otherwise.
CONTROL ⇢ static:

Use SSL for the control connection or fail.
ALL ⇢ static:

Use SSL for all communication or fail

class FileType

cURL file types

Fields

FILE ⇢ static:

File
DIRECTORY ⇢ static:

Directory
SYMLINK ⇢ static:

Symbolic Link
DEVICE_CHAR ⇢ static:
NAMEDPIPE ⇢ static:

Named Pipe
SOCKET ⇢ static:

Socket
DOOR ⇢ static:

Door. This is only possible on Sun Solaris now

class Option

cURL request options for set_option()

Fields

URL ⇢ static:

The full URL to get/put
PORT ⇢ static:

Port number to connect to, if other than default.
PROXY ⇢ static:

Name of proxy to use.
USERPWD ⇢ static:

"user:password;options" to use when fetching.
PROXYUSERPWD ⇢ static:

"user:password" to use with proxy.
RANGE ⇢ static:

Range to get, specified as an ASCII string.
ERRORBUFFER ⇢ static:

Buffer to receive error messages in, must be at least CURL_ERROR_SIZE bytes big.
TIMEOUT ⇢ static:

Time-out the read operation after this amount of seconds
INFILESIZE ⇢ static:

If the CURLOPT_INFILE is used, this can be used to inform libcurl about how large the file being sent really is. That allows better error checking and better verifies that the upload was successful. -1 means unknown size. For large file support, there is also a _LARGE version of the key which takes an off_t type, allowing platforms with larger off_t sizes to handle larger files. See below for INFILESIZE_LARGE.
POSTFIELDS ⇢ static:

POST static input fields.
REFERER ⇢ static:

Set the referrer page (needed by some CGIs)
FTPPORT ⇢ static:

Set the FTP PORT string (interface name, named or numerical IP address) Use i.e '-' to use default address.
USERAGENT ⇢ static:

Set the User-Agent string (examined by some CGIs)
LOW_SPEED_LIMIT ⇢ static:

Set the "low speed limit"
LOW_SPEED_TIME ⇢ static:

Set the "low speed time"
RESUME_FROM ⇢ static:

Set the continuation offset. Note there is also a _LARGE version of this key which uses off_t types, allowing for large file offsets on platforms which use larger-than-32-bit off_t's. Look below for RESUME_FROM_LARGE.
COOKIE ⇢ static:

Set cookie in request:
HTTPHEADER ⇢ static:

This points to a list of HTTP header strings. This list is also used for RTSP (in spite of its name)
HTTPPOST ⇢ static:

This points to a linked list of post entries.
SSLCERT ⇢ static:

name of the file keeping your private SSL-certificate
KEYPASSWD ⇢ static:

password for the SSL or SSH private key
CRLF ⇢ static:

send TYPE parameter?
QUOTE ⇢ static:

send linked-list of QUOTE commands
COOKIEFILE ⇢ static:

point to a file to read the initial cookies from, also enables "cookie awareness"
SSLVERSION ⇢ static:

What version to specifically try to use. See CURL_SSLVERSION defines below.
TIMECONDITION ⇢ static:

What kind of HTTP time condition to use, see defines
TIMEVALUE ⇢ static:

Time to use with the above condition. Specified in number of seconds since 1 Jan 1970
CUSTOMREQUEST ⇢ static:

Custom request, for customizing the get command like HTTP: DELETE, TRACE and others FTP: to use a different list command
STDERR ⇢ static:

FILE handle to use instead of stderr
POSTQUOTE ⇢ static:

send linked-list of post-transfer QUOTE commands
VERBOSE ⇢ static:

talk a lot
HEADER ⇢ static:

throw the header out too
NOPROGRESS ⇢ static:

shut off the progress meter
NOBODY ⇢ static:

use HEAD to get http document
FAILONERROR ⇢ static:

no output on http error codes >= 400
UPLOAD ⇢ static:

this is an upload
POST ⇢ static:

HTTP POST method
DIRLISTONLY ⇢ static:

bare names when listing directories
APPEND ⇢ static:

Append instead of overwrite on upload!
NETRC ⇢ static:

Specify whether to read the user+password from the .netrc or the URL. This must be one of the CURL_NETRC_ enums below. @static
FOLLOWLOCATION ⇢ static:

use Location: Luke!
TRANSFERTEXT ⇢ static:

transfer data in text/ASCII format
PUT ⇢ static:

HTTP PUT
AUTOREFERER ⇢ static:

We want the referrer field set automatically when following locations
PROXYPORT ⇢ static:

Port of the proxy, can be set in the proxy string as well with: "[host]:[port]"
POSTFIELDSIZE ⇢ static:

size of the POST input data, if strlen() is not good to use
HTTPPROXYTUNNEL ⇢ static:

tunnel non-http operations through a HTTP proxy
INTERFACE ⇢ static:

Set the interface string to use as outgoing network interface
KRBLEVEL ⇢ static:

Set the krb4/5 security level, this also enables krb4/5 awareness. This is a string, 'clear', 'safe', 'confidential' or 'private'. If the string is set but doesn't match one of these, 'private' will be used.
SSL_VERIFYPEER ⇢ static:

Set if we should verify the peer in ssl handshake, set 1 to verify.
CAINFO ⇢ static:

The CApath or CAfile used to validate the peer certificate this option is used only if SSL_VERIFYPEER is true
MAXREDIRS ⇢ static:

Maximum number of http redirects to follow
FILETIME ⇢ static:

Pass a long set to 1 to get the date of the requested document (if possible)! Pass a zero to shut it off.
TELNETOPTIONS ⇢ static:

This points to a linked list of telnet options
MAXCONNECTS ⇢ static:

Max amount of cached alive connections
FRESH_CONNECT ⇢ static:

Set to explicitly use a new connection for the upcoming transfer. Do not use this unless you're absolutely sure of this, as it makes the operation slower and is less friendly for the network.
FORBID_REUSE ⇢ static:

Set to explicitly forbid the upcoming transfer's connection to be re-used when done. Do not use this unless you're absolutely sure of this, as it makes the operation slower and is less friendly for the network.
CONNECTTIMEOUT ⇢ static:

Time-out connect operations after this amount of seconds, if connects are OK within this time, then fine... This only aborts the connect phase.
HTTPGET ⇢ static:

Set this to force the HTTP request to get back to GET. Only really usable if POST, PUT or a custom request have been used first.
SSL_VERIFYHOST ⇢ static:

Set if we should verify the Common name from the peer certificate in ssl handshake, set 1 to check existence, 2 to ensure that it matches the provided hostname.
COOKIEJAR ⇢ static:

Specify which file name to write all known cookies in after completed operation. Set file name to "-" (dash) to make it go to stdout.
SSL_CIPHER_LIST ⇢ static:

Specify which SSL ciphers to use
HTTP_VERSION ⇢ static:

Specify which HTTP version to use! This must be set to one of the CURL_HTTP_VERSION enums set below. @static
FTP_USE_EPSV ⇢ static:

Specifically switch on or off the FTP engine's use of the EPSV command. By default, that one will always be attempted before the more traditional PASV command.
SSLCERTTYPE ⇢ static:

type of the file keeping your SSL-certificate ("DER", "PEM", "ENG")
SSLKEY ⇢ static:

name of the file keeping your private SSL-key
SSLKEYTYPE ⇢ static:

type of the file keeping your private SSL-key ("DER", "PEM", "ENG")
SSLENGINE ⇢ static:

crypto engine for the SSL-sub system
SSLENGINE_DEFAULT ⇢ static:

set the crypto engine for the SSL-sub system as default the param has no meaning...
DNS_USE_GLOBAL_CACHE ⇢ static:

DEPRECATED, do not use!
DNS_CACHE_TIMEOUT ⇢ static:

DNS cache timeout
PREQUOTE ⇢ static:

send linked-list of pre-transfer QUOTE commands
COOKIESESSION ⇢ static:

mark this as start of a cookie session
CAPATH ⇢ static:

The CApath directory used to validate the peer certificate this option is used only if SSL_VERIFYPEER is true
BUFFERSIZE ⇢ static:

Instruct libcurl to use a smaller receive buffer
NOSIGNAL ⇢ static:

Instruct libcurl to not use any signal/alarm handlers, even when using timeouts. This option is useful for multi-threaded applications. See libcurl-the-guide for more background information.
SHARE ⇢ static:

Provide a CURLShare for mutexing non-ts data
PROXYTYPE ⇢ static:

indicates type of proxy. accepted values are CURLPROXY_HTTP (default), CURLPROXY_HTTPS, CURLPROXY_SOCKS4, CURLPROXY_SOCKS4A and CURLPROXY_SOCKS5.
ACCEPT_ENCODING ⇢ static:

Set the Accept-Encoding string. Use this to tell a server you would like the response to be compressed. Before 7.21.6, this was known as CURLOPT_ENCODING
PRIVATE ⇢ static:

Set pointer to private data
HTTP200ALIASES ⇢ static:

Set aliases for HTTP 200 in the HTTP Response header
UNRESTRICTED_AUTH ⇢ static:

Continue to send authentication (user+password) when following locations, even when hostname changed. This can potentially send off the name and password to whatever host the server decides.
FTP_USE_EPRT ⇢ static:

Specifically switch on or off the FTP engine's use of the EPRT command ( it also disables the LPRT attempt). By default, those ones will always be attempted before the good old traditional PORT command.
HTTPAUTH ⇢ static:

Set this to a bitmask value to enable the particular authentications methods you like. Use this in combination with CURLOPT_USERPWD. Note that setting multiple bits may cause extra network round-trips.
FTP_CREATE_MISSING_DIRS ⇢ static:

FTP Option that causes missing dirs to be created on the remote server. In 7.19.4 we introduced the convenience enums for this option using the CURLFTP_CREATE_DIR prefix.
PROXYAUTH ⇢ static:

Set this to a bitmask value to enable the particular authentications methods you like. Use this in combination with CURLOPT_PROXYUSERPWD. Note that setting multiple bits may cause extra network round-trips.
FTP_RESPONSE_TIMEOUT ⇢ static:

FTP option that changes the timeout, in seconds, associated with getting a response. This is different from transfer timeout time and essentially places a demand on the FTP server to acknowledge commands in a timely manner.
SERVER_RESPONSE_TIMEOUT ⇢ static:

This option that changes the timeout, in seconds, associated with getting a response from a server.
IPRESOLVE ⇢ static:

Set this option to one of the CURL_IPRESOLVE_ defines (see below) to tell libcurl to use those IP versions only. This only has effect on systems with support for more than one, i.e IPv4 and IPv6.
MAXFILESIZE ⇢ static:

Set this option to limit the size of a file that will be downloaded from an HTTP or FTP server.

There is also _LARGE version which adds large file support for platforms which have larger off_t sizes. See MAXFILESIZE_LARGE below.

INFILESIZE_LARGE ⇢ static:

See the comment for INFILESIZE above, but in short, specifies the size of the file being uploaded. -1 means unknown.
RESUME_FROM_LARGE ⇢ static:

Sets the continuation offset. There is also a CURLOPTTYPE_LONG version of this; look above for RESUME_FROM.
MAXFILESIZE_LARGE ⇢ static:

Sets the maximum size of data that will be downloaded from an HTTP or FTP server. See MAXFILESIZE above for the LONG version.
NETRC_FILE ⇢ static:

Set this option to the file name of your .netrc file you want libcurl to parse (using the CURLOPT_NETRC option). If not set, libcurl will do a poor attempt to find the user's home directory and check for a .netrc file in there.
USE_SSL ⇢ static:

Enable SSL/TLS for FTP, pick one of: CURLUSESSL_TRY - try using SSL, proceed anyway otherwise CURLUSESSL_CONTROL - SSL for the control connection or fail CURLUSESSL_ALL - SSL for all communication or fail
POSTFIELDSIZE_LARGE ⇢ static:

The _LARGE version of the standard POSTFIELDSIZE option
TCP_NODELAY ⇢ static:

Enable/disable the TCP Nagle algorithm
FTPSSLAUTH ⇢ static:

When FTP over SSL/TLS is selected (with CURLOPT_USE_SSL), this option can be used to change libcurl's default action which is to first try "AUTH SSL" and then "AUTH TLS" in this order, and proceed when a OK response has been received.

Available parameters are: CURLFTPAUTH_DEFAULT - let libcurl decide CURLFTPAUTH_SSL - try "AUTH SSL" first, then TLS CURLFTPAUTH_TLS - try "AUTH TLS" first, then SSL

FTP_ACCOUNT ⇢ static:

null-terminated string for pass on to the FTP server when asked for "account" info
COOKIELIST ⇢ static:

feed cookie into cookie engine
IGNORE_CONTENT_LENGTH ⇢ static:

ignore Content-Length
FTP_SKIP_PASV_IP ⇢ static:

Set to non-zero to skip the IP address received in a 227 PASV FTP server response. Typically used for FTP-SSL purposes but is not restricted to that. libcurl will then instead use the same IP address it used for the control connection.
FTP_FILEMETHOD ⇢ static:

Select "file method" to use when doing FTP, see the curl ftpmethod above.
LOCALPORT ⇢ static:

Local port number to bind the socket to
LOCALPORTRANGE ⇢ static:

Number of ports to try, including the first one set with LOCALPORT. Thus, setting it to 1 will make no additional attempts but the first.
CONNECT_ONLY ⇢ static:

no transfer, set up connection and let application use the socket by extracting it with CURLINFO_LASTSOCKET
MAX_SEND_SPEED_LARGE ⇢ static:

limit-rate: maximum number of bytes per second to send
MAX_RECV_SPEED_LARGE ⇢ static:

limit-rate: maximum number of bytes per second to receive
FTP_ALTERNATIVE_TO_USER ⇢ static:

Pointer to command string to send if USER/PASS fails.
SSL_SESSIONID_CACHE ⇢ static:

set to 0 to disable session ID re-use for this transfer, default is enabled (== 1)
SSH_AUTH_TYPES ⇢ static:

allowed SSH authentication methods
SSH_PUBLIC_KEYFILE ⇢ static:

Used by scp/sftp to do public key authentication
SSH_PRIVATE_KEYFILE ⇢ static:

Used by scp/sftp to do private key authentication
FTP_SSL_CCC ⇢ static:

Send CCC (Clear Command Channel) after authentication
TIMEOUT_MS ⇢ static:

Same as TIMEOUT, but with ms resolution
CONNECTTIMEOUT_MS ⇢ static:

Same as CONNECTTIMEOUT, but with ms resolution
HTTP_TRANSFER_DECODING ⇢ static:

set to zero to disable the libcurl's decoding and thus pass the raw body data to the application even when it is encoded/compressed via transfter encoding
HTTP_CONTENT_DECODING ⇢ static:

set to zero to disable the libcurl's decoding and thus pass the raw body data to the application even when it is encoded/compressed via content encoding
NEW_FILE_PERMS ⇢ static:

Permission used when creating new files on the remote server for protocols that support it, SFTP/SCP/FILE
NEW_DIRECTORY_PERMS ⇢ static:

Permission used when creating new directories on the remote server for protocols that support it, SFTP/SCP/FILE
POSTREDIR ⇢ static:

Set the behavior of POST when redirecting. Values must be set to one of CURL_REDIR defines below. This used to be called CURLOPT_POST301 @static
SSH_HOST_PUBLIC_KEY_MD5 ⇢ static:

used by scp/sftp to verify the host's public key
COPYPOSTFIELDS ⇢ static:

POST volatile input fields.
PROXY_TRANSFER_MODE ⇢ static:

set transfer mode (;type=<a|i>) when doing FTP via an HTTP proxy
CRLFILE ⇢ static:

CRL file
ISSUERCERT ⇢ static:

Issuer certificate
ADDRESS_SCOPE ⇢ static:

(IPv6) Address scope
CERTINFO ⇢ static:

Collect certificate chain info and allow it to get retrievable with CURLINFO_CERTINFO after the transfer is complete.
USERNAME ⇢ static:

"name" (username) to use when fetching.
PASSWORD ⇢ static:

"pwd" (password) to use when fetching.
PROXYUSERNAME ⇢ static:

"name" (username) to use with Proxy when fetching.
PROXYPASSWORD ⇢ static:

"pwd" (password) to use with Proxy when fetching.
NOPROXY ⇢ static:

Comma separated list of hostnames defining no-proxy zones. These should match both hostnames directly, and hostnames within a domain. For example, local.com will match local.com and www.local.com, but NOT notlocal.com or www.notlocal.com. For compatibility with other implementations of this, .local.com will be considered to be the same as local.com. A single is the only valid wildcard, and effectively disables the use of proxy.
TFTP_BLKSIZE ⇢ static:

block size for TFTP transfers
SOCKS5_GSSAPI_NEC ⇢ static:

Socks Service
PROTOCOLS ⇢ static:

set the bitmask for the protocols that are allowed to be used for the transfer, which thus helps the app which takes URLs from users or other external inputs and want to restrict what protocol(s) to deal with. Defaults to CURLPROTO_ALL.
REDIR_PROTOCOLS ⇢ static:

set the bitmask for the protocols that libcurl is allowed to follow to, as a subset of the CURLOPT_PROTOCOLS ones. That means the protocol needs to be set in both bitmasks to be allowed to get redirected to.
SSH_KNOWNHOSTS ⇢ static:

set the SSH knownhost file name to use
MAIL_FROM ⇢ static:

set the SMTP mail originator
MAIL_RCPT ⇢ static:

set the list of SMTP mail receiver(s)
FTP_USE_PRET ⇢ static:

FTP: send PRET before PASV
RTSP_REQUEST ⇢ static:

RTSP request method (OPTIONS, SETUP, PLAY, etc...)
RTSP_SESSION_ID ⇢ static:

The RTSP session identifier
RTSP_STREAM_URI ⇢ static:

The RTSP stream URI
RTSP_TRANSPORT ⇢ static:

The Transport: header to use in RTSP requests
RTSP_CLIENT_CSEQ ⇢ static:

Manually initialize the client RTSP CSeq for this handle
RTSP_SERVER_CSEQ ⇢ static:

Manually initialize the server RTSP CSeq for this handle
WILDCARDMATCH ⇢ static:

Turn on wildcard matching
RESOLVE ⇢ static:

send linked-list of name:port:address sets
TLSAUTH_USERNAME ⇢ static:

Set a username for authenticated TLS
TLSAUTH_PASSWORD ⇢ static:

Set a password for authenticated TLS
TLSAUTH_TYPE ⇢ static:

Set authentication type for authenticated TLS
TRANSFER_ENCODING ⇢ static:

Set to 1 to enable the "TE:" header in HTTP requests to ask for compressed transfer-encoded responses. Set to 0 to disable the use of TE: in outgoing requests. The current default is 0, but it might change in a future libcurl release.

libcurl will ask for the compressed methods it knows of, and if that isn't any, it will not ask for transfer-encoding at all even if this option is set to 1.

GSSAPI_DELEGATION ⇢ static:

allow GSSAPI credential delegation
DNS_SERVERS ⇢ static:

Set the name servers to use for DNS resolution
ACCEPTTIMEOUT_MS ⇢ static:

Time-out accept operations (currently for FTP only) after this amount of milliseconds.
TCP_KEEPALIVE ⇢ static:

Set TCP keepalive
TCP_KEEPIDLE ⇢ static:

non-universal keepalive idle time (Linux, AIX, HP-UX, more)
TCP_KEEPINTVL ⇢ static:

non-universal keepalive interval (Linux, AIX, HP-UX, more)
SSL_OPTIONS ⇢ static:

Enable/disable specific SSL features with a bitmask, see CURLSSLOPT_ @static
MAIL_AUTH ⇢ static:

Set the SMTP auth originator
SASL_IR ⇢ static:

Enable/disable SASL initial response
XOAUTH2_BEARER ⇢ static:

The XOAUTH2 bearer token
DNS_INTERFACE ⇢ static:

Set the interface string to use as outgoing network interface for DNS requests. Only supported by the c-ares DNS backend
DNS_LOCAL_IP4 ⇢ static:

Set the local IPv4 address to use for outgoing DNS requests. Only supported by the c-ares DNS backend
DNS_LOCAL_IP6 ⇢ static:

Set the local IPv6 address to use for outgoing DNS requests. Only supported by the c-ares DNS backend
LOGIN_OPTIONS ⇢ static:

Set authentication options directly
SSL_ENABLE_NPN ⇢ static:

Enable/disable TLS NPN extension (http2 over ssl might fail without)
SSL_ENABLE_ALPN ⇢ static:

Enable/disable TLS ALPN extension (http2 over ssl might fail without)
EXPECT_100_TIMEOUT_MS ⇢ static:

Time to wait for a response to a HTTP request containing an Expect: 100-continue header before sending the data anyway.
PROXYHEADER ⇢ static:

This points to a list of headers used for proxy requests only.
HEADEROPT ⇢ static:

Pass in a bitmask of "header options"
PINNEDPUBLICKEY ⇢ static:

The public key in DER form used to validate the peer public key this option is used only if SSL_VERIFYPEER is true
UNIX_SOCKET_PATH ⇢ static:

Path to Unix domain socket
SSL_VERIFYSTATUS ⇢ static:

Set if we should verify the certificate status.
SSL_FALSESTART ⇢ static:

Set if we should enable TLS false start.
PATH_AS_IS ⇢ static:

Do not squash dot-dot sequences
PROXY_SERVICE_NAME ⇢ static:

Proxy Service Name
SERVICE_NAME ⇢ static:

Service Name
PIPEWAIT ⇢ static:

Wait/don't wait for pipe/mutex to clarify
DEFAULT_PROTOCOL ⇢ static:

Set the protocol used when curl is given a URL without a protocol
STREAM_WEIGHT ⇢ static:

Set stream weight, 1 - 256 (default is 16)
STREAM_DEPENDS ⇢ static:

Set stream dependency on another CURL handle
STREAM_DEPENDS_E ⇢ static:

Set E-xclusive stream dependency on another CURL handle
TFTP_NO_OPTIONS ⇢ static:

Do not send any tftp option requests to the server
CONNECT_TO ⇢ static:

Linked-list of host:port:connect-to-host:connect-to-port, overrides the URL's host:port (only for the network layer)
TCP_FASTOPEN ⇢ static:

Set TCP Fast Open
KEEP_SENDING_ON_ERROR ⇢ static:

Continue to send data if the server responds early with an HTTP status code >= 300
PROXY_CAINFO ⇢ static:

The CApath or CAfile used to validate the proxy certificate this option is used only if PROXY_SSL_VERIFYPEER is true
PROXY_CAPATH ⇢ static:

The CApath directory used to validate the proxy certificate this option is used only if PROXY_SSL_VERIFYPEER is true
PROXY_SSL_VERIFYPEER ⇢ static:

Set if we should verify the proxy in ssl handshake, set 1 to verify.
PROXY_SSL_VERIFYHOST ⇢ static:

Set if we should verify the Common name from the proxy certificate in ssl handshake, set 1 to check existence, 2 to ensure that it matches the provided hostname.
PROXY_SSLVERSION ⇢ static:

What version to specifically try to use for proxy. See CURL_SSLVERSION defines below.
PROXY_TLSAUTH_USERNAME ⇢ static:

Set a username for authenticated TLS for proxy
PROXY_TLSAUTH_PASSWORD ⇢ static:

Set a password for authenticated TLS for proxy
PROXY_TLSAUTH_TYPE ⇢ static:

Set authentication type for authenticated TLS for proxy
PROXY_SSLCERT ⇢ static:

name of the file keeping your private SSL-certificate for proxy
PROXY_SSLCERTTYPE ⇢ static:

type of the file keeping your SSL-certificate ("DER", "PEM", "ENG") for proxy
PROXY_SSLKEY ⇢ static:

name of the file keeping your private SSL-key for proxy
PROXY_SSLKEYTYPE ⇢ static:

type of the file keeping your private SSL-key ("DER", "PEM", "ENG") for proxy
PROXY_KEYPASSWD ⇢ static:

password for the SSL private key for proxy
PROXY_SSL_CIPHER_LIST ⇢ static:

Specify which SSL ciphers to use for proxy
PROXY_CRLFILE ⇢ static:

CRL file for proxy
PROXY_SSL_OPTIONS ⇢ static:

Enable/disable specific SSL features with a bitmask for proxy, see CURLSSLOPT_ @static
PRE_PROXY ⇢ static:

Name of pre proxy to use.
PROXY_PINNEDPUBLICKEY ⇢ static:

The public key in DER form used to validate the proxy public key this option is used only if PROXY_SSL_VERIFYPEER is true
ABSTRACT_UNIX_SOCKET ⇢ static:

Path to an abstract Unix domain socket
SUPPRESS_CONNECT_HEADERS ⇢ static:

Suppress proxy CONNECT response headers from user callbacks
REQUEST_TARGET ⇢ static:

The request target, instead of extracted from the URL
SOCKS5_AUTH ⇢ static:

bitmask of allowed auth methods for connections to SOCKS5 proxies
SSH_COMPRESSION ⇢ static:

Enable/disable SSH compression
MIMEPOST ⇢ static:

Post MIME data.
READDATA ⇢ static:

The data that will be used as the body of the request.
TIMEVALUE_LARGE ⇢ static:

Time to use with the CURLOPT_TIMECONDITION. Specified in number of seconds since 1 Jan 1970.
HAPPY_EYEBALLS_TIMEOUT_MS ⇢ static:

Head start in milliseconds to give happy eyeballs.
HAPROXYPROTOCOL ⇢ static:

send HAProxy PROXY protocol header?
DNS_SHUFFLE_ADDRESSES ⇢ static:

shuffle addresses before use when DNS returns multiple
TLS13_CIPHERS ⇢ static:

Specify which TLS 1.3 ciphers suites to use
PROXY_TLS13_CIPHERS ⇢ static:

Specify which TLS 1.3 ciphers suites to use with a proxy
DISALLOW_USERNAME_IN_URL ⇢ static:

Disallow specifying username/login in URL.
DOH_URL ⇢ static:

DNS-over-HTTPS URL
UPLOAD_BUFFERSIZE ⇢ static:

Preferred buffer size to use for uploads
UPKEEP_INTERVAL_MS ⇢ static:

Time in ms between connection upkeep calls for long-lived connections.
CURLU ⇢ static:

Specify URL using CURL URL API.
HTTP09_ALLOWED ⇢ static:

set this to 1L to allow HTTP/0.9 responses or 0L to disallow
ALTSVC_CTRL ⇢ static:

alt-svc control bitmask
ALTSVC ⇢ static:

alt-svc cache file name to possibly read from/write to
MAXAGE_CONN ⇢ static:

maximum age of a connection to consider it for reuse (in seconds)
SASL_AUTHZID ⇢ static:

SASL authorisation identity

curl

Properties

Functions

get_time(date_string)

Parameters

Returns

Classes

class Info

Fields

class CurlMime

Methods

CurlMime(curl) ⇢ Constructor

add(name, value)

Parameters

Returns

add_as(value, type)

Parameters

Returns

add_data(data)

Parameters

Returns

add_file(name, value)

Parameters

Returns

add_mime(mime, type)

Parameters

Returns

set_encoding(encoding)

Parameters

get_pointer()

class CurlList

Methods

CurlList(items)

Parameters

close()

get_pointer()

class Curl

Methods

Curl() ⇢ Constructor

set_option(option, value)

Parameters

Returns

Notes

get_info(info)

Parameters

Returns

escape(str)

Parameters

Returns

Notes

unescape(str)

Parameters

Returns

send()

Returns

reset()

close()

Notes

get_pointer()

class Auth

Fields

class UseSSL

Fields

class FileType

Fields

class Option

Fields

Search

Navigation