curl

This module provides native bindings to libcurl's client-side URL transfer library, supporting DICT, FILE, FTP, FTPS, Gopher, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, Telnet and TFTP. libcurl supports SSL certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies, cookies, user+password authentication (Basic, Digest, NTLM, Negotiate, Kerberos), file transfer resume, http proxy tunneling and more!

The following example shows the basic usage that visits a website and prints the output.

import curl

var c = curl.Curl()
c.set_option(curl.Option.URL, 'www.google.com')
c.set_option(curl.Option.FOLLOWLOCATION)

echo c.send()
c.close()

See Libcurl's official documentation for more information.

Fields

curl.version ➝ string: The libcurl version.

Functions

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

@params:
- string date_string

@returns: number

Classes

class Info

cURL request and response informations for get_info()

static .EFFECTIVE_URL ➝

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.

static .RESPONSE_CODE ➝

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

static .TOTAL_TIME ➝

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

static .NAMELOOKUP_TIME ➝

The total time in seconds from the start until the name resolving was completed.

static .CONNECT_TIME ➝

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

static .PRETRANSFER_TIME ➝

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.

static .SIZE_UPLOAD ➝

The total amount of bytes that were uploaded.

static .SIZE_DOWNLOAD ➝

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.

static .SPEED_DOWNLOAD ➝

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

static .SPEED_UPLOAD ➝

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

static .HEADER_SIZE ➝

The total size of all the headers received. Measured in number of bytes.

static .REQUEST_SIZE ➝

The total size of the issued requests. This is so far only for HTTP requests.

static .SSL_VERIFYRESULT ➝

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

static .FILETIME ➝

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.

static .CONTENT_LENGTH_DOWNLOAD ➝

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.

static .CONTENT_LENGTH_UPLOAD ➝

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

static .STARTTRANSFER_TIME ➝

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.

static .CONTENT_TYPE ➝

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.

static .REDIRECT_TIME ➝

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

static .REDIRECT_COUNT ➝

The total number of redirections that were actually followed.

static .HTTP_CONNECTCODE ➝

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

static .HTTPAUTH_AVAIL ➝

A bitmask indicating the authentication method(s) available according to the previous response.

static .PROXYAUTH_AVAIL ➝

A bitmask indicating the authentication method(s) available according to the previous response.

static .OS_ERRNO ➝

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.

static .NUM_CONNECTS ➝

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.

static .COOKIELIST ➝

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.

static .FTP_ENTRY_PATH ➝

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.

static .REDIRECT_URL ➝

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.

static .PRIMARY_IP ➝

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

static .APPCONNECT_TIME ➝

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.

static .CERTINFO ➝

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.

static .CONDITION_UNMET ➝

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

static .RTSP_SESSION_ID ➝

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.

static .RTSP_CLIENT_CSEQ ➝

The next CSeq that will be used by the application.

static .RTSP_SERVER_CSEQ ➝

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.

static .RTSP_CSEQ_RECV ➝

The most recently received CSeq from the server.

static .PRIMARY_PORT ➝

The destination port of the most recent connection done with the curl instance.

static .LOCAL_IP ➝

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

static .LOCAL_PORT ➝

The local port number of the most recent connection done with the curl instance.

static .HTTP_VERSION ➝

The HTTP version used in the last http connection.

static .PROXY_SSL_VERIFYRESULT ➝

The result of the certificate verification that was requested (using the Options.PROXY_SSL_VERIFYPEER option.

static .PROTOCOL ➝

The protocol used in the last request.

static .SCHEME ➝

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

static .TOTAL_TIME_T ➝

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

static .NAMELOOKUP_TIME_T ➝

The total time in microseconds from the start until the name resolving was completed.

static .CONNECT_TIME_T ➝

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

static .PRETRANSFER_TIME_T ➝

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.

static .STARTTRANSFER_TIME_T ➝

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.

static .REDIRECT_TIME_T ➝

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.

static .APPCONNECT_TIME_T ➝

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.

static .RETRY_AFTER ➝

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.

.CurlMime(curl) ➝ Constructor

curl.CurlMime constructor

@params:
- Curl curl

.add(name, value)

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

@params:
- string name
- any value

@returns: bool

.add_as(value, type)

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

@params:
- any value
- string type

@returns: bool

.add_data(data)

Adds a new mime part with the given data.

@params:
- any data

@returns: bool

.add_file(name, value)

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

@params:
- string name
- string|instance value

@returns: bool

.add_mime(mime, type)

Adds a new mime subpart with the given mime.

@params:
- CurlMime mime
- string type

@returns: bool

.set_encoding(encoding)

Sets the encoding with which the mime will be transfered.

@params:
- string encoding

.get_pointer()

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

class CurlList

cURL list interface.

.CurlList(items)

@constrctor

@params:
- 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

.Curl() ➝ Constructor

curl.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().

@notes:

Strings passed to curl as arguments, must not exceed 8MB in size.

The order in which the options are set does not matter.

@params:
- Option option
- any value

@returns: boolean

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

@params:
- 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).

@notes:

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

@params:
- string str

@returns: string

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

@params:
- 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

static .NONE ➝: No HTTP authentication
static .BASIC ➝: HTTP Basic authentication (default)
static .DIGEST ➝: HTTP Digest authentication
static .NEGOTIATE ➝: HTTP Negotiate (SPNEGO) authentication
static .GSSNEGOTIATE ➝: Alias for CURLAUTH_NEGOTIATE (deprecated)
static .NTLM ➝: HTTP NTLM authentication
static .DIGEST_IE ➝: HTTP Digest authentication with IE flavour
static .NTLM_WB ➝: HTTP NTLM authentication delegated to winbind helper
static .BEARER ➝: HTTP Bearer token authentication
static .ONLY ➝: Use together with a single other type to force no authentication or just that single type.
static .ANY ➝: All fine types set
static .ANYSAFE ➝: All fine types except Basic
static .SSH_ANY ➝: All types of SSH authentication supported by the server
static .SSH_NONE ➝: No SSH allowed
static .SSH_PUBLICKEY ➝: Public/private key files for SSH authentication.
static .SSH_PASSWORD ➝: Password for SSH authentication.
static .SSH_HOST ➝: Host key files for SSH authentication.
static .SSH_KEYBOARD ➝: Keyboard interactive SSH authentication.
static .SSH_AGENT ➝: Agent (ssh-agent, pageant, etc.) for SSH authentication.
static .SSH_GSSAPI ➝: gssapi (kerberos, etc.) for SSH authentication.
static .SSH_DEFAULT ➝: The default SSH authentication (same as ANY).

class UseSSL

cURL request options for set_option()

static .NONE ➝: Do not attempt to use SSL.
static .TRY ➝: Try using SSL, proceed anyway otherwise.
static .CONTROL ➝: Use SSL for the control connection or fail.
static .ALL ➝: Use SSL for all communication or fail

class FileType

cURL file types

static .FILE ➝: File
static .DIRECTORY ➝: Directory
static .SYMLINK ➝: Symbolic Link

static .DEVICE_CHAR ➝ {#curl.FileType.DEVICE_CHAR} :

static .NAMEDPIPE ➝: Named Pipe
static .SOCKET ➝: Socket
static .DOOR ➝: Door. This is only possible on Sun Solaris now

class Option

cURL request options for set_option()

static .URL ➝

The full URL to get/put

static .PORT ➝

Port number to connect to, if other than default.

static .PROXY ➝

Name of proxy to use.

static .USERPWD ➝

"user:password;options" to use when fetching.

static .PROXYUSERPWD ➝

"user:password" to use with proxy.

static .RANGE ➝

Range to get, specified as an ASCII string.

static .ERRORBUFFER ➝

Buffer to receive error messages in, must be at least CURL_ERROR_SIZE bytes big.

static .TIMEOUT ➝

Time-out the read operation after this amount of seconds

static .INFILESIZE ➝

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.

static .POSTFIELDS ➝

POST static input fields.

static .REFERER ➝

Set the referrer page (needed by some CGIs)

static .FTPPORT ➝

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

static .USERAGENT ➝

Set the User-Agent string (examined by some CGIs)

static .LOW_SPEED_LIMIT ➝

Set the "low speed limit"

static .LOW_SPEED_TIME ➝

Set the "low speed time"

static .RESUME_FROM ➝

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.

static .COOKIE ➝

Set cookie in request:

static .HTTPHEADER ➝

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

static .HTTPPOST ➝

This points to a linked list of post entries.

static .SSLCERT ➝

name of the file keeping your private SSL-certificate

static .KEYPASSWD ➝

password for the SSL or SSH private key

static .CRLF ➝

send TYPE parameter?

static .QUOTE ➝

send linked-list of QUOTE commands

static .COOKIEFILE ➝

point to a file to read the initial cookies from, also enables "cookie awareness"

static .SSLVERSION ➝

What version to specifically try to use. See CURL_SSLVERSION defines below.

static .TIMECONDITION ➝

What kind of HTTP time condition to use, see defines

static .TIMEVALUE ➝

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

static .CUSTOMREQUEST ➝

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

static .STDERR ➝

FILE handle to use instead of stderr

static .POSTQUOTE ➝

send linked-list of post-transfer QUOTE commands

static .VERBOSE ➝

talk a lot

static .HEADER ➝

throw the header out too

static .NOPROGRESS ➝

shut off the progress meter

static .NOBODY ➝

use HEAD to get http document

static .FAILONERROR ➝

no output on http error codes >= 400

static .UPLOAD ➝

this is an upload

static .POST ➝

HTTP POST method

static .DIRLISTONLY ➝

bare names when listing directories

static .APPEND ➝

Append instead of overwrite on upload!

static .NETRC ➝

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

static .FOLLOWLOCATION ➝

use Location: Luke!

static .TRANSFERTEXT ➝

transfer data in text/ASCII format

static .PUT ➝

HTTP PUT

static .AUTOREFERER ➝

We want the referrer field set automatically when following locations

static .PROXYPORT ➝

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

static .POSTFIELDSIZE ➝

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

static .HTTPPROXYTUNNEL ➝

tunnel non-http operations through a HTTP proxy

static .INTERFACE ➝

Set the interface string to use as outgoing network interface

static .KRBLEVEL ➝

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.

static .SSL_VERIFYPEER ➝

Set if we should verify the peer in ssl handshake, set 1 to verify.

static .CAINFO ➝

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

static .MAXREDIRS ➝

Maximum number of http redirects to follow

static .FILETIME ➝

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

static .TELNETOPTIONS ➝

This points to a linked list of telnet options

static .MAXCONNECTS ➝

Max amount of cached alive connections

static .FRESH_CONNECT ➝

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.

static .FORBID_REUSE ➝

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.

static .CONNECTTIMEOUT ➝

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

static .HTTPGET ➝

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.

static .SSL_VERIFYHOST ➝

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.

static .COOKIEJAR ➝

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

static .SSL_CIPHER_LIST ➝

Specify which SSL ciphers to use

static .HTTP_VERSION ➝

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

static .FTP_USE_EPSV ➝

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.

static .SSLCERTTYPE ➝

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

static .SSLKEY ➝

name of the file keeping your private SSL-key

static .SSLKEYTYPE ➝

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

static .SSLENGINE ➝

crypto engine for the SSL-sub system

static .SSLENGINE_DEFAULT ➝

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

static .DNS_USE_GLOBAL_CACHE ➝

DEPRECATED, do not use!

static .DNS_CACHE_TIMEOUT ➝

DNS cache timeout

static .PREQUOTE ➝

send linked-list of pre-transfer QUOTE commands

static .COOKIESESSION ➝

mark this as start of a cookie session

static .CAPATH ➝

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

static .BUFFERSIZE ➝

Instruct libcurl to use a smaller receive buffer

static .NOSIGNAL ➝

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.

static .SHARE ➝

Provide a CURLShare for mutexing non-ts data

static .PROXYTYPE ➝

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

static .ACCEPT_ENCODING ➝

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

static .PRIVATE ➝

Set pointer to private data

static .HTTP200ALIASES ➝

Set aliases for HTTP 200 in the HTTP Response header

static .UNRESTRICTED_AUTH ➝

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.

static .FTP_USE_EPRT ➝

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.

static .HTTPAUTH ➝

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.

static .FTP_CREATE_MISSING_DIRS ➝

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.

static .PROXYAUTH ➝

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.

static .FTP_RESPONSE_TIMEOUT ➝

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.

static .SERVER_RESPONSE_TIMEOUT ➝

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

static .IPRESOLVE ➝

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.

static .MAXFILESIZE ➝

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.

static .INFILESIZE_LARGE ➝

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

static .RESUME_FROM_LARGE ➝

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

static .MAXFILESIZE_LARGE ➝

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

static .NETRC_FILE ➝

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.

static .USE_SSL ➝

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

static .POSTFIELDSIZE_LARGE ➝

The _LARGE version of the standard POSTFIELDSIZE option

static .TCP_NODELAY ➝

Enable/disable the TCP Nagle algorithm

static .FTPSSLAUTH ➝

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

static .FTP_ACCOUNT ➝

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

static .COOKIELIST ➝

feed cookie into cookie engine

static .IGNORE_CONTENT_LENGTH ➝

ignore Content-Length

static .FTP_SKIP_PASV_IP ➝

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.

static .FTP_FILEMETHOD ➝

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

static .LOCALPORT ➝

Local port number to bind the socket to

static .LOCALPORTRANGE ➝

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.

static .CONNECT_ONLY ➝

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

static .MAX_SEND_SPEED_LARGE ➝

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

static .MAX_RECV_SPEED_LARGE ➝

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

static .FTP_ALTERNATIVE_TO_USER ➝

Pointer to command string to send if USER/PASS fails.

static .SSL_SESSIONID_CACHE ➝

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

static .SSH_AUTH_TYPES ➝

allowed SSH authentication methods

static .SSH_PUBLIC_KEYFILE ➝

Used by scp/sftp to do public key authentication

static .SSH_PRIVATE_KEYFILE ➝

Used by scp/sftp to do private key authentication

static .FTP_SSL_CCC ➝

Send CCC (Clear Command Channel) after authentication

static .TIMEOUT_MS ➝

Same as TIMEOUT, but with ms resolution

static .CONNECTTIMEOUT_MS ➝

Same as CONNECTTIMEOUT, but with ms resolution

static .HTTP_TRANSFER_DECODING ➝

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

static .HTTP_CONTENT_DECODING ➝

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

static .NEW_FILE_PERMS ➝

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

static .NEW_DIRECTORY_PERMS ➝

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

static .POSTREDIR ➝

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

static .SSH_HOST_PUBLIC_KEY_MD5 ➝

used by scp/sftp to verify the host's public key

static .COPYPOSTFIELDS ➝

POST volatile input fields.

static .PROXY_TRANSFER_MODE ➝

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

static .CRLFILE ➝

CRL file

static .ISSUERCERT ➝

Issuer certificate

static .ADDRESS_SCOPE ➝

(IPv6) Address scope

static .CERTINFO ➝

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

static .USERNAME ➝

"name" (username) to use when fetching.

static .PASSWORD ➝

"pwd" (password) to use when fetching.

static .PROXYUSERNAME ➝

"name" (username) to use with Proxy when fetching.

static .PROXYPASSWORD ➝

"pwd" (password) to use with Proxy when fetching.

static .NOPROXY ➝

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.

static .TFTP_BLKSIZE ➝

block size for TFTP transfers

static .SOCKS5_GSSAPI_NEC ➝

Socks Service

static .PROTOCOLS ➝

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.

static .REDIR_PROTOCOLS ➝

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.

static .SSH_KNOWNHOSTS ➝

set the SSH knownhost file name to use

static .MAIL_FROM ➝

set the SMTP mail originator

static .MAIL_RCPT ➝

set the list of SMTP mail receiver(s)

static .FTP_USE_PRET ➝

FTP: send PRET before PASV

static .RTSP_REQUEST ➝

RTSP request method (OPTIONS, SETUP, PLAY, etc...)

static .RTSP_SESSION_ID ➝

The RTSP session identifier

static .RTSP_STREAM_URI ➝

The RTSP stream URI

static .RTSP_TRANSPORT ➝

The Transport: header to use in RTSP requests

static .RTSP_CLIENT_CSEQ ➝

Manually initialize the client RTSP CSeq for this handle

static .RTSP_SERVER_CSEQ ➝

Manually initialize the server RTSP CSeq for this handle

static .WILDCARDMATCH ➝

Turn on wildcard matching

static .RESOLVE ➝

send linked-list of name:port:address sets

static .TLSAUTH_USERNAME ➝

Set a username for authenticated TLS

static .TLSAUTH_PASSWORD ➝

Set a password for authenticated TLS

static .TLSAUTH_TYPE ➝

Set authentication type for authenticated TLS

static .TRANSFER_ENCODING ➝

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.

static .GSSAPI_DELEGATION ➝

allow GSSAPI credential delegation

static .DNS_SERVERS ➝

Set the name servers to use for DNS resolution

static .ACCEPTTIMEOUT_MS ➝

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

static .TCP_KEEPALIVE ➝

Set TCP keepalive

static .TCP_KEEPIDLE ➝

non-universal keepalive idle time (Linux, AIX, HP-UX, more)

static .TCP_KEEPINTVL ➝

non-universal keepalive interval (Linux, AIX, HP-UX, more)

static .SSL_OPTIONS ➝

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

static .MAIL_AUTH ➝

Set the SMTP auth originator

static .SASL_IR ➝

Enable/disable SASL initial response

static .XOAUTH2_BEARER ➝

The XOAUTH2 bearer token

static .DNS_INTERFACE ➝

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

static .DNS_LOCAL_IP4 ➝

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

static .DNS_LOCAL_IP6 ➝

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

static .LOGIN_OPTIONS ➝

Set authentication options directly

static .SSL_ENABLE_NPN ➝

Enable/disable TLS NPN extension (http2 over ssl might fail without)

static .SSL_ENABLE_ALPN ➝

Enable/disable TLS ALPN extension (http2 over ssl might fail without)

static .EXPECT_100_TIMEOUT_MS ➝

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

static .PROXYHEADER ➝

This points to a list of headers used for proxy requests only.

static .HEADEROPT ➝

Pass in a bitmask of "header options"

static .PINNEDPUBLICKEY ➝

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

static .UNIX_SOCKET_PATH ➝

Path to Unix domain socket

static .SSL_VERIFYSTATUS ➝

Set if we should verify the certificate status.

static .SSL_FALSESTART ➝

Set if we should enable TLS false start.

static .PATH_AS_IS ➝

Do not squash dot-dot sequences

static .PROXY_SERVICE_NAME ➝

Proxy Service Name

static .SERVICE_NAME ➝

Service Name

static .PIPEWAIT ➝

Wait/don't wait for pipe/mutex to clarify

static .DEFAULT_PROTOCOL ➝

Set the protocol used when curl is given a URL without a protocol

static .STREAM_WEIGHT ➝

Set stream weight, 1 - 256 (default is 16)

static .STREAM_DEPENDS ➝

Set stream dependency on another CURL handle

static .STREAM_DEPENDS_E ➝

Set E-xclusive stream dependency on another CURL handle

static .TFTP_NO_OPTIONS ➝

Do not send any tftp option requests to the server

static .CONNECT_TO ➝

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

static .TCP_FASTOPEN ➝

Set TCP Fast Open

static .KEEP_SENDING_ON_ERROR ➝

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

static .PROXY_CAINFO ➝

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

static .PROXY_CAPATH ➝

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

static .PROXY_SSL_VERIFYPEER ➝

Set if we should verify the proxy in ssl handshake, set 1 to verify.

static .PROXY_SSL_VERIFYHOST ➝

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.

static .PROXY_SSLVERSION ➝

What version to specifically try to use for proxy. See CURL_SSLVERSION defines below.

static .PROXY_TLSAUTH_USERNAME ➝

Set a username for authenticated TLS for proxy

static .PROXY_TLSAUTH_PASSWORD ➝

Set a password for authenticated TLS for proxy

static .PROXY_TLSAUTH_TYPE ➝

Set authentication type for authenticated TLS for proxy

static .PROXY_SSLCERT ➝

name of the file keeping your private SSL-certificate for proxy

static .PROXY_SSLCERTTYPE ➝

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

static .PROXY_SSLKEY ➝

name of the file keeping your private SSL-key for proxy

static .PROXY_SSLKEYTYPE ➝

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

static .PROXY_KEYPASSWD ➝

password for the SSL private key for proxy

static .PROXY_SSL_CIPHER_LIST ➝

Specify which SSL ciphers to use for proxy

static .PROXY_CRLFILE ➝

CRL file for proxy

static .PROXY_SSL_OPTIONS ➝

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

static .PRE_PROXY ➝

Name of pre proxy to use.

static .PROXY_PINNEDPUBLICKEY ➝

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

static .ABSTRACT_UNIX_SOCKET ➝

Path to an abstract Unix domain socket

static .SUPPRESS_CONNECT_HEADERS ➝

Suppress proxy CONNECT response headers from user callbacks

static .REQUEST_TARGET ➝

The request target, instead of extracted from the URL

static .SOCKS5_AUTH ➝

bitmask of allowed auth methods for connections to SOCKS5 proxies

static .SSH_COMPRESSION ➝

Enable/disable SSH compression

static .MIMEPOST ➝

Post MIME data.

static .READDATA ➝

The data that will be used as the body of the request.

static .TIMEVALUE_LARGE ➝

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

static .HAPPY_EYEBALLS_TIMEOUT_MS ➝

Head start in milliseconds to give happy eyeballs.

static .HAPROXYPROTOCOL ➝

send HAProxy PROXY protocol header?

static .DNS_SHUFFLE_ADDRESSES ➝

shuffle addresses before use when DNS returns multiple

static .TLS13_CIPHERS ➝

Specify which TLS 1.3 ciphers suites to use

static .PROXY_TLS13_CIPHERS ➝

Specify which TLS 1.3 ciphers suites to use with a proxy

static .DISALLOW_USERNAME_IN_URL ➝

Disallow specifying username/login in URL.

static .DOH_URL ➝

DNS-over-HTTPS URL

static .UPLOAD_BUFFERSIZE ➝

Preferred buffer size to use for uploads

static .UPKEEP_INTERVAL_MS ➝

Time in ms between connection upkeep calls for long-lived connections.

static .CURLU ➝

Specify URL using CURL URL API.

static .HTTP09_ALLOWED ➝

set this to 1L to allow HTTP/0.9 responses or 0L to disallow

static .ALTSVC_CTRL ➝

alt-svc control bitmask

static .ALTSVC ➝

alt-svc cache file name to possibly read from/write to

static .MAXAGE_CONN ➝

maximum age of a connection to consider it for reuse (in seconds)

static .SASL_AUTHZID ➝

SASL authorisation identity

curl

Fields

Functions

Classes

Search

Navigation