Listing curl features and options

Description

The functions curl_version() and curl_options() show the available features, protocols and options supported by the local version of libcurl.

You can use curl_options_table() to lookup the type for each option: most options take a string, number, or TRUE/FALSE value, but some options need a special enum/bitmask value: these are listed in the sections below.

Usage

curl_options(filter = "")

curl_options_table(filter = "")

curl_version()

Arguments

Details

Several curl options take an enum or bitmask value, for which the libcurl manual pages give symbolic names. These constants are exported as R variables, so you can copy such values literally from the libcurl documentation:

h <- new_handle()
handle_setopt(h, http_version = CURL_HTTP_VERSION_1_1)
handle_setopt(h, httpauth = CURLAUTH_NEGOTIATE)

For bitmask options, each constant is a single distinct bit, so where the libcurl documentation combines flags with |, you can simply add them up:

handle_setopt(h, httpauth = CURLAUTH_BASIC + CURLAUTH_DIGEST)
handle_setopt(h, altsvc_ctrl = CURLALTSVC_H1 + CURLALTSVC_H2)

Note that a few wide bitmasks such as CURLAUTH_ANY exceed the range of R integers and are therefore stored as doubles, holding the exact same numeric value as their C counterparts.

The sections below list the supported options with their values, in the same order as the corresponding libcurl manual pages. As usual with handle_setopt(), the R option name is the CURLOPT_ constant, lowercase and without the prefix, e.g. CURLOPT_HTTPAUTH becomes httpauth.

CURLOPT_ALTSVC_CTRL

Bitmask to enable Alt-Svc support, see https://curl.se/libcurl/c/CURLOPT_ALTSVC_CTRL.html.

• CURLALTSVC_H1: accept alternative services offered over HTTP/1.1

• CURLALTSVC_H2: accept alternative services offered over HTTP/2

• CURLALTSVC_H3: accept alternative services offered over HTTP/3

• CURLALTSVC_READONLYFILE: do not write the alt-svc cache back to the file

CURLOPT_FOLLOWLOCATION

In addition to classic TRUE/FALSE, libcurl >= 8.13 supports these modes, see https://curl.se/libcurl/c/CURLOPT_FOLLOWLOCATION.html.

• CURLFOLLOW_ALL: follow redirects (same as TRUE)

• CURLFOLLOW_OBEYCODE: follow redirects, but do not use the custom method in the follow-up request when the HTTP code (301, 302, 303) instructs so

• CURLFOLLOW_FIRSTONLY: only use the custom method in the first request, always reset it in the next

CURLOPT_FTP_CREATE_MISSING_DIRS

See https://curl.se/libcurl/c/CURLOPT_FTP_CREATE_MISSING_DIRS.html.

• CURLFTP_CREATE_DIR_NONE: do not create missing directories

• CURLFTP_CREATE_DIR: create a missing directory, fail if that does not work

• CURLFTP_CREATE_DIR_RETRY: retry the CWD command again if the directory could not be created, in case it was created by a third party in the meantime

CURLOPT_FTP_FILEMETHOD

Select how to reach a file on an FTP(S) server, see https://curl.se/libcurl/c/CURLOPT_FTP_FILEMETHOD.html.

• CURLFTPMETHOD_DEFAULT: let libcurl pick (same as MULTICWD)

• CURLFTPMETHOD_MULTICWD: a CWD command for each path part

• CURLFTPMETHOD_NOCWD: no CWD at all, use the full path in every command

• CURLFTPMETHOD_SINGLECWD: one CWD with the full target directory

CURLOPT_FTP_SSL_CCC

Clear Command Channel mode, see https://curl.se/libcurl/c/CURLOPT_FTP_SSL_CCC.html.

• CURLFTPSSL_CCC_NONE: do not attempt to shut down the SSL/TLS layer

• CURLFTPSSL_CCC_PASSIVE: do not initiate the shutdown, wait for the server

• CURLFTPSSL_CCC_ACTIVE: initiate the shutdown ourselves

CURLOPT_FTPSSLAUTH

Order in which to attempt TLS vs SSL when upgrading an FTP connection, see https://curl.se/libcurl/c/CURLOPT_FTPSSLAUTH.html.

• CURLFTPAUTH_DEFAULT: let libcurl decide

• CURLFTPAUTH_SSL: try ⁠AUTH SSL⁠ first

• CURLFTPAUTH_TLS: try ⁠AUTH TLS⁠ first

CURLOPT_GSSAPI_DELEGATION

See https://curl.se/libcurl/c/CURLOPT_GSSAPI_DELEGATION.html.

• CURLGSSAPI_DELEGATION_NONE: no delegation (default)

• CURLGSSAPI_DELEGATION_POLICY_FLAG: delegate if the OK-AS-DELEGATE flag is set in the service ticket

• CURLGSSAPI_DELEGATION_FLAG: unconditionally allow delegation

CURLOPT_HEADEROPT

How to send custom headers to a proxy, see https://curl.se/libcurl/c/CURLOPT_HEADEROPT.html.

• CURLHEADER_UNIFIED: the headers set with httpheader are also sent to the proxy

• CURLHEADER_SEPARATE: only headers set with proxyheader are sent to the proxy

CURLOPT_HSTS_CTRL

Bitmask to enable HSTS (HTTP Strict Transport Security), see https://curl.se/libcurl/c/CURLOPT_HSTS_CTRL.html.

• CURLHSTS_ENABLE: enable the in-memory HSTS cache

• CURLHSTS_READONLYFILE: do not write the HSTS cache back to the file

CURLOPT_HTTP_VERSION

Preferred HTTP protocol version, see https://curl.se/libcurl/c/CURLOPT_HTTP_VERSION.html.

• CURL_HTTP_VERSION_NONE: no preference, let libcurl choose (default)

• CURL_HTTP_VERSION_1_0: enforce HTTP 1.0

• CURL_HTTP_VERSION_1_1: enforce HTTP 1.1

• CURL_HTTP_VERSION_2_0: attempt HTTP 2, fall back to HTTP 1.1 (CURL_HTTP_VERSION_2 is an alias)

• CURL_HTTP_VERSION_2TLS: attempt HTTP 2 for HTTPS only, HTTP 1.1 otherwise

• CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE: use HTTP 2 without HTTP/1.1 Upgrade

• CURL_HTTP_VERSION_3: attempt HTTP 3, fall back to earlier versions

• CURL_HTTP_VERSION_3ONLY: use HTTP 3 or fail

CURLOPT_HTTPAUTH

Bitmask of HTTP authentication methods libcurl may use, see https://curl.se/libcurl/c/CURLOPT_HTTPAUTH.html. The same values apply to proxyauth (CURLOPT_PROXYAUTH).

• CURLAUTH_NONE: no authentication

• CURLAUTH_BASIC: HTTP Basic authentication (default)

• CURLAUTH_DIGEST: HTTP Digest authentication

• CURLAUTH_DIGEST_IE: HTTP Digest authentication with an IE flavor

• CURLAUTH_BEARER: HTTP Bearer token (OAuth 2.0) authentication

• CURLAUTH_NEGOTIATE: HTTP Negotiate (SPNEGO) authentication (CURLAUTH_GSSAPI is an alias)

• CURLAUTH_NTLM: HTTP NTLM authentication

• CURLAUTH_AWS_SIGV4: HTTP AWS V4 signature authentication

• CURLAUTH_ANY: all supported methods, libcurl picks the most secure

• CURLAUTH_ANYSAFE: all supported methods except Basic

• CURLAUTH_ONLY: modifier bit: use only the method set alongside it, e.g. CURLAUTH_ONLY + CURLAUTH_DIGEST

CURLOPT_IPRESOLVE

See https://curl.se/libcurl/c/CURLOPT_IPRESOLVE.html.

• CURL_IPRESOLVE_WHATEVER: resolve to any IP version (default)

• CURL_IPRESOLVE_V4: only use IPv4 addresses

• CURL_IPRESOLVE_V6: only use IPv6 addresses

CURLOPT_MIME_OPTIONS

See https://curl.se/libcurl/c/CURLOPT_MIME_OPTIONS.html.

• CURLMIMEOPT_FORMESCAPE: backslash-escape quotes and backslashes in multipart form field and file names

CURLOPT_NETRC

Whether to read credentials from the .netrc file, see https://curl.se/libcurl/c/CURLOPT_NETRC.html.

• CURL_NETRC_IGNORED: ignore the netrc file (default)

• CURL_NETRC_OPTIONAL: use the netrc file, but credentials in the URL take precedence

• CURL_NETRC_REQUIRED: only use the netrc file, ignore credentials in the URL

CURLOPT_POSTREDIR

Bitmask of redirect codes after which a POST must remain a POST, see https://curl.se/libcurl/c/CURLOPT_POSTREDIR.html.

• CURL_REDIR_POST_301: keep the POST method after a 301 redirect

• CURL_REDIR_POST_302: keep the POST method after a 302 redirect

• CURL_REDIR_POST_303: keep the POST method after a 303 redirect

• CURL_REDIR_POST_ALL: all of the above

• CURL_REDIR_GET_ALL: convert to GET on all redirects (default)

CURLOPT_PROXYTYPE

Type of the proxy set with proxy, see https://curl.se/libcurl/c/CURLOPT_PROXYTYPE.html.

• CURLPROXY_HTTP: HTTP proxy (default)

• CURLPROXY_HTTPS: HTTPS proxy using HTTP/1.x

• CURLPROXY_HTTPS2: HTTPS proxy, attempt HTTP/2

• CURLPROXY_HTTP_1_0: HTTP proxy, force HTTP 1.0

• CURLPROXY_SOCKS4: SOCKS4 proxy

• CURLPROXY_SOCKS4A: SOCKS4a proxy, proxy resolves the hostname

• CURLPROXY_SOCKS5: SOCKS5 proxy

• CURLPROXY_SOCKS5_HOSTNAME: SOCKS5 proxy, proxy resolves the hostname

CURLOPT_SOCKS5_AUTH

Bitmask of allowed methods for SOCKS5 proxy authentication, see https://curl.se/libcurl/c/CURLOPT_SOCKS5_AUTH.html: CURLAUTH_BASIC (username/password), CURLAUTH_GSSAPI and CURLAUTH_NONE.

CURLOPT_SSH_AUTH_TYPES

Bitmask of authentication types for SFTP/SCP connections, see https://curl.se/libcurl/c/CURLOPT_SSH_AUTH_TYPES.html.

• CURLSSH_AUTH_PUBLICKEY: public/private key files

• CURLSSH_AUTH_PASSWORD: password

• CURLSSH_AUTH_HOST: host key files

• CURLSSH_AUTH_KEYBOARD: keyboard interactive

• CURLSSH_AUTH_AGENT: ssh-agent

• CURLSSH_AUTH_GSSAPI: gssapi (kerberos, ...)

• CURLSSH_AUTH_ANY: any method (default, CURLSSH_AUTH_DEFAULT is an alias)

• CURLSSH_AUTH_NONE: no allowed methods

CURLOPT_SSL_OPTIONS

Bitmask of SSL behavior options, see https://curl.se/libcurl/c/CURLOPT_SSL_OPTIONS.html. The same values apply to proxy_ssl_options (CURLOPT_PROXY_SSL_OPTIONS).

• CURLSSLOPT_ALLOW_BEAST: allow the BEAST SSL vulnerability for interoperability reasons

• CURLSSLOPT_NO_REVOKE: disable certificate revocation checks (Schannel)

• CURLSSLOPT_NO_PARTIALCHAIN: do not accept partial certificate chains

• CURLSSLOPT_REVOKE_BEST_EFFORT: ignore revocation check failures due to missing/offline distribution points (Schannel)

• CURLSSLOPT_NATIVE_CA: use the operating system's native CA store

• CURLSSLOPT_AUTO_CLIENT_CERT: automatically locate and use a client certificate for authentication (Schannel)

CURLOPT_SSLVERSION

Preferred TLS/SSL version, see https://curl.se/libcurl/c/CURLOPT_SSLVERSION.html. The same values apply to proxy_sslversion (CURLOPT_PROXY_SSLVERSION).

• CURL_SSLVERSION_DEFAULT: default, currently the minimum is TLS v1.0

• CURL_SSLVERSION_TLSv1: TLS v1.0 or later

• CURL_SSLVERSION_TLSv1_0: TLS v1.0 or later

• CURL_SSLVERSION_TLSv1_1: TLS v1.1 or later

• CURL_SSLVERSION_TLSv1_2: TLS v1.2 or later

• CURL_SSLVERSION_TLSv1_3: TLS v1.3 or later

The maximum TLS version can be set by adding one of these to the value above, e.g. CURL_SSLVERSION_TLSv1_1 + CURL_SSLVERSION_MAX_TLSv1_2:

• CURL_SSLVERSION_MAX_DEFAULT: the highest supported TLS version (CURL_SSLVERSION_MAX_NONE has the same effect)

• CURL_SSLVERSION_MAX_TLSv1_0: at most TLS v1.0

• CURL_SSLVERSION_MAX_TLSv1_1: at most TLS v1.1

• CURL_SSLVERSION_MAX_TLSv1_2: at most TLS v1.2

• CURL_SSLVERSION_MAX_TLSv1_3: at most TLS v1.3

CURLOPT_TIMECONDITION

How to compare the timevalue timestamp, see https://curl.se/libcurl/c/CURLOPT_TIMECONDITION.html.

• CURL_TIMECOND_NONE: no time condition (default)

• CURL_TIMECOND_IFMODSINCE: only transfer if modified since timevalue

• CURL_TIMECOND_IFUNMODSINCE: only transfer if not modified since timevalue

• CURL_TIMECOND_LASTMOD: (FTP only)

CURLOPT_USE_SSL

Request TLS upgrade for FTP, SMTP, POP3 and IMAP transfers, see https://curl.se/libcurl/c/CURLOPT_USE_SSL.html.

• CURLUSESSL_NONE: do not attempt to use SSL (default)

• CURLUSESSL_TRY: try SSL, proceed as normal otherwise

• CURLUSESSL_CONTROL: require SSL for the control connection, or fail

• CURLUSESSL_ALL: require SSL for all communication, or fail

CURLOPT_WS_OPTIONS

Bitmask with websocket behavior options, see https://curl.se/libcurl/c/CURLOPT_WS_OPTIONS.html.

• CURLWS_RAW_MODE: deliver raw websocket traffic to the write callback

• CURLWS_NOAUTOPONG: disable the automatic reply to PING frames (libcurl >= 8.14)

Other symbols

The sections above cover the option values supported by handle_setopt(). Use curl_symbols() was previously used to lookup the value of any symbol from the libcurl symbol table, along with the libcurl version in which it was introduced, deprecated, or removed.

See Also

handle_setopt()

Examples

# Available options
curl_options()

# List proxy options
curl_options("proxy")
# Curl/ssl version info
curl_version()
# Set options using symbolic constants
h <- new_handle()
handle_setopt(h, http_version = CURL_HTTP_VERSION_1_1)
handle_setopt(h, httpauth = CURLAUTH_BASIC + CURLAUTH_DIGEST)