% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/options.R, R/utilities.R, R/values.R
\name{curl_options}
\alias{curl_options}
\alias{curl_options_table}
\alias{curl_symbols}
\alias{curl_version}
\alias{CURL_HTTP_VERSION_1_0}
\alias{CURL_HTTP_VERSION_1_1}
\alias{CURL_HTTP_VERSION_2}
\alias{CURL_HTTP_VERSION_2_0}
\alias{CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE}
\alias{CURL_HTTP_VERSION_2TLS}
\alias{CURL_HTTP_VERSION_3}
\alias{CURL_HTTP_VERSION_3ONLY}
\alias{CURL_HTTP_VERSION_NONE}
\alias{CURL_IPRESOLVE_V4}
\alias{CURL_IPRESOLVE_V6}
\alias{CURL_IPRESOLVE_WHATEVER}
\alias{CURL_NETRC_IGNORED}
\alias{CURL_NETRC_OPTIONAL}
\alias{CURL_NETRC_REQUIRED}
\alias{CURL_REDIR_GET_ALL}
\alias{CURL_REDIR_POST_301}
\alias{CURL_REDIR_POST_302}
\alias{CURL_REDIR_POST_303}
\alias{CURL_REDIR_POST_ALL}
\alias{CURL_SSLVERSION_DEFAULT}
\alias{CURL_SSLVERSION_MAX_DEFAULT}
\alias{CURL_SSLVERSION_MAX_NONE}
\alias{CURL_SSLVERSION_MAX_TLSv1_0}
\alias{CURL_SSLVERSION_MAX_TLSv1_1}
\alias{CURL_SSLVERSION_MAX_TLSv1_2}
\alias{CURL_SSLVERSION_MAX_TLSv1_3}
\alias{CURL_SSLVERSION_TLSv1}
\alias{CURL_SSLVERSION_TLSv1_0}
\alias{CURL_SSLVERSION_TLSv1_1}
\alias{CURL_SSLVERSION_TLSv1_2}
\alias{CURL_SSLVERSION_TLSv1_3}
\alias{CURL_TIMECOND_IFMODSINCE}
\alias{CURL_TIMECOND_IFUNMODSINCE}
\alias{CURL_TIMECOND_LASTMOD}
\alias{CURL_TIMECOND_NONE}
\alias{CURLALTSVC_H1}
\alias{CURLALTSVC_H2}
\alias{CURLALTSVC_H3}
\alias{CURLALTSVC_READONLYFILE}
\alias{CURLAUTH_ANY}
\alias{CURLAUTH_ANYSAFE}
\alias{CURLAUTH_AWS_SIGV4}
\alias{CURLAUTH_BASIC}
\alias{CURLAUTH_BEARER}
\alias{CURLAUTH_DIGEST}
\alias{CURLAUTH_DIGEST_IE}
\alias{CURLAUTH_GSSAPI}
\alias{CURLAUTH_NEGOTIATE}
\alias{CURLAUTH_NONE}
\alias{CURLAUTH_NTLM}
\alias{CURLAUTH_ONLY}
\alias{CURLFOLLOW_ALL}
\alias{CURLFOLLOW_FIRSTONLY}
\alias{CURLFOLLOW_OBEYCODE}
\alias{CURLFTP_CREATE_DIR}
\alias{CURLFTP_CREATE_DIR_NONE}
\alias{CURLFTP_CREATE_DIR_RETRY}
\alias{CURLFTPAUTH_DEFAULT}
\alias{CURLFTPAUTH_SSL}
\alias{CURLFTPAUTH_TLS}
\alias{CURLFTPMETHOD_DEFAULT}
\alias{CURLFTPMETHOD_MULTICWD}
\alias{CURLFTPMETHOD_NOCWD}
\alias{CURLFTPMETHOD_SINGLECWD}
\alias{CURLFTPSSL_CCC_ACTIVE}
\alias{CURLFTPSSL_CCC_NONE}
\alias{CURLFTPSSL_CCC_PASSIVE}
\alias{CURLGSSAPI_DELEGATION_FLAG}
\alias{CURLGSSAPI_DELEGATION_NONE}
\alias{CURLGSSAPI_DELEGATION_POLICY_FLAG}
\alias{CURLHEADER_SEPARATE}
\alias{CURLHEADER_UNIFIED}
\alias{CURLHSTS_ENABLE}
\alias{CURLHSTS_READONLYFILE}
\alias{CURLMIMEOPT_FORMESCAPE}
\alias{CURLPROXY_HTTP}
\alias{CURLPROXY_HTTP_1_0}
\alias{CURLPROXY_HTTPS}
\alias{CURLPROXY_HTTPS2}
\alias{CURLPROXY_SOCKS4}
\alias{CURLPROXY_SOCKS4A}
\alias{CURLPROXY_SOCKS5}
\alias{CURLPROXY_SOCKS5_HOSTNAME}
\alias{CURLSSH_AUTH_AGENT}
\alias{CURLSSH_AUTH_ANY}
\alias{CURLSSH_AUTH_DEFAULT}
\alias{CURLSSH_AUTH_GSSAPI}
\alias{CURLSSH_AUTH_HOST}
\alias{CURLSSH_AUTH_KEYBOARD}
\alias{CURLSSH_AUTH_NONE}
\alias{CURLSSH_AUTH_PASSWORD}
\alias{CURLSSH_AUTH_PUBLICKEY}
\alias{CURLSSLOPT_ALLOW_BEAST}
\alias{CURLSSLOPT_AUTO_CLIENT_CERT}
\alias{CURLSSLOPT_NATIVE_CA}
\alias{CURLSSLOPT_NO_PARTIALCHAIN}
\alias{CURLSSLOPT_NO_REVOKE}
\alias{CURLSSLOPT_REVOKE_BEST_EFFORT}
\alias{CURLUSESSL_ALL}
\alias{CURLUSESSL_CONTROL}
\alias{CURLUSESSL_NONE}
\alias{CURLUSESSL_TRY}
\alias{CURLWS_NOAUTOPONG}
\alias{CURLWS_RAW_MODE}
\title{Listing curl features and options}
\usage{
curl_options(filter = "")

curl_options_table(filter = "")

curl_version()
}
\arguments{
\item{filter}{string: only return options with string in name}
}
\description{
The functions \code{curl_version()} and \code{curl_options()} show the available
features, protocols and options supported by the local version of libcurl.

You can use \code{curl_options_table()} to lookup the type for each
option: most options take a string, number, or \code{TRUE}/\code{FALSE} value, but some
options need a special enum/bitmask value: these are listed in the sections below.
}
\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:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{h <- new_handle()
handle_setopt(h, http_version = CURL_HTTP_VERSION_1_1)
handle_setopt(h, httpauth = CURLAUTH_NEGOTIATE)
}\if{html}{\out{</div>}}

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

\if{html}{\out{<div class="sourceCode r">}}\preformatted{handle_setopt(h, httpauth = CURLAUTH_BASIC + CURLAUTH_DIGEST)
handle_setopt(h, altsvc_ctrl = CURLALTSVC_H1 + CURLALTSVC_H2)
}\if{html}{\out{</div>}}

Note that a few wide bitmasks such as \code{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
\code{\link[=handle_setopt]{handle_setopt()}}, the R option name is the \code{CURLOPT_} constant, lowercase
and without the prefix, e.g. \code{CURLOPT_HTTPAUTH} becomes \code{httpauth}.
}
\section{CURLOPT_ALTSVC_CTRL}{
Bitmask to enable Alt-Svc support, see
\url{https://curl.se/libcurl/c/CURLOPT_ALTSVC_CTRL.html}.
\itemize{
\item \code{CURLALTSVC_H1}: accept alternative services offered over HTTP/1.1
\item \code{CURLALTSVC_H2}: accept alternative services offered over HTTP/2
\item \code{CURLALTSVC_H3}: accept alternative services offered over HTTP/3
\item \code{CURLALTSVC_READONLYFILE}: do not write the alt-svc cache back to the file
}
}

\section{CURLOPT_FOLLOWLOCATION}{
In addition to classic \code{TRUE}/\code{FALSE}, libcurl >= 8.13 supports these
modes, see \url{https://curl.se/libcurl/c/CURLOPT_FOLLOWLOCATION.html}.
\itemize{
\item \code{CURLFOLLOW_ALL}: follow redirects (same as \code{TRUE})
\item \code{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
\item \code{CURLFOLLOW_FIRSTONLY}: only use the custom method in the first
request, always reset it in the next
}
}

\section{CURLOPT_FTP_CREATE_MISSING_DIRS}{
See \url{https://curl.se/libcurl/c/CURLOPT_FTP_CREATE_MISSING_DIRS.html}.
\itemize{
\item \code{CURLFTP_CREATE_DIR_NONE}: do not create missing directories
\item \code{CURLFTP_CREATE_DIR}: create a missing directory, fail if that does not work
\item \code{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
}
}

\section{CURLOPT_FTP_FILEMETHOD}{
Select how to reach a file on an FTP(S) server, see
\url{https://curl.se/libcurl/c/CURLOPT_FTP_FILEMETHOD.html}.
\itemize{
\item \code{CURLFTPMETHOD_DEFAULT}: let libcurl pick (same as \code{MULTICWD})
\item \code{CURLFTPMETHOD_MULTICWD}: a \code{CWD} command for each path part
\item \code{CURLFTPMETHOD_NOCWD}: no \code{CWD} at all, use the full path in every command
\item \code{CURLFTPMETHOD_SINGLECWD}: one \code{CWD} with the full target directory
}
}

\section{CURLOPT_FTP_SSL_CCC}{
Clear Command Channel mode, see
\url{https://curl.se/libcurl/c/CURLOPT_FTP_SSL_CCC.html}.
\itemize{
\item \code{CURLFTPSSL_CCC_NONE}: do not attempt to shut down the SSL/TLS layer
\item \code{CURLFTPSSL_CCC_PASSIVE}: do not initiate the shutdown, wait for the server
\item \code{CURLFTPSSL_CCC_ACTIVE}: initiate the shutdown ourselves
}
}

\section{CURLOPT_FTPSSLAUTH}{
Order in which to attempt TLS vs SSL when upgrading an FTP connection, see
\url{https://curl.se/libcurl/c/CURLOPT_FTPSSLAUTH.html}.
\itemize{
\item \code{CURLFTPAUTH_DEFAULT}: let libcurl decide
\item \code{CURLFTPAUTH_SSL}: try \verb{AUTH SSL} first
\item \code{CURLFTPAUTH_TLS}: try \verb{AUTH TLS} first
}
}

\section{CURLOPT_GSSAPI_DELEGATION}{
See \url{https://curl.se/libcurl/c/CURLOPT_GSSAPI_DELEGATION.html}.
\itemize{
\item \code{CURLGSSAPI_DELEGATION_NONE}: no delegation (default)
\item \code{CURLGSSAPI_DELEGATION_POLICY_FLAG}: delegate if the OK-AS-DELEGATE
flag is set in the service ticket
\item \code{CURLGSSAPI_DELEGATION_FLAG}: unconditionally allow delegation
}
}

\section{CURLOPT_HEADEROPT}{
How to send custom headers to a proxy, see
\url{https://curl.se/libcurl/c/CURLOPT_HEADEROPT.html}.
\itemize{
\item \code{CURLHEADER_UNIFIED}: the headers set with \code{httpheader} are also sent
to the proxy
\item \code{CURLHEADER_SEPARATE}: only headers set with \code{proxyheader} are sent to
the proxy
}
}

\section{CURLOPT_HSTS_CTRL}{
Bitmask to enable HSTS (HTTP Strict Transport Security), see
\url{https://curl.se/libcurl/c/CURLOPT_HSTS_CTRL.html}.
\itemize{
\item \code{CURLHSTS_ENABLE}: enable the in-memory HSTS cache
\item \code{CURLHSTS_READONLYFILE}: do not write the HSTS cache back to the file
}
}

\section{CURLOPT_HTTP_VERSION}{
Preferred HTTP protocol version, see
\url{https://curl.se/libcurl/c/CURLOPT_HTTP_VERSION.html}.
\itemize{
\item \code{CURL_HTTP_VERSION_NONE}: no preference, let libcurl choose (default)
\item \code{CURL_HTTP_VERSION_1_0}: enforce HTTP 1.0
\item \code{CURL_HTTP_VERSION_1_1}: enforce HTTP 1.1
\item \code{CURL_HTTP_VERSION_2_0}: attempt HTTP 2, fall back to HTTP 1.1
(\code{CURL_HTTP_VERSION_2} is an alias)
\item \code{CURL_HTTP_VERSION_2TLS}: attempt HTTP 2 for HTTPS only, HTTP 1.1 otherwise
\item \code{CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE}: use HTTP 2 without HTTP/1.1 Upgrade
\item \code{CURL_HTTP_VERSION_3}: attempt HTTP 3, fall back to earlier versions
\item \code{CURL_HTTP_VERSION_3ONLY}: use HTTP 3 or fail
}
}

\section{CURLOPT_HTTPAUTH}{
Bitmask of HTTP authentication methods libcurl may use, see
\url{https://curl.se/libcurl/c/CURLOPT_HTTPAUTH.html}. The same values apply
to \code{proxyauth}
(\href{https://curl.se/libcurl/c/CURLOPT_PROXYAUTH.html}{CURLOPT_PROXYAUTH}).
\itemize{
\item \code{CURLAUTH_NONE}: no authentication
\item \code{CURLAUTH_BASIC}: HTTP Basic authentication (default)
\item \code{CURLAUTH_DIGEST}: HTTP Digest authentication
\item \code{CURLAUTH_DIGEST_IE}: HTTP Digest authentication with an IE flavor
\item \code{CURLAUTH_BEARER}: HTTP Bearer token (OAuth 2.0) authentication
\item \code{CURLAUTH_NEGOTIATE}: HTTP Negotiate (SPNEGO) authentication
(\code{CURLAUTH_GSSAPI} is an alias)
\item \code{CURLAUTH_NTLM}: HTTP NTLM authentication
\item \code{CURLAUTH_AWS_SIGV4}: HTTP AWS V4 signature authentication
\item \code{CURLAUTH_ANY}: all supported methods, libcurl picks the most secure
\item \code{CURLAUTH_ANYSAFE}: all supported methods except Basic
\item \code{CURLAUTH_ONLY}: modifier bit: use only the method set alongside it,
e.g. \code{CURLAUTH_ONLY + CURLAUTH_DIGEST}
}
}

\section{CURLOPT_IPRESOLVE}{
See \url{https://curl.se/libcurl/c/CURLOPT_IPRESOLVE.html}.
\itemize{
\item \code{CURL_IPRESOLVE_WHATEVER}: resolve to any IP version (default)
\item \code{CURL_IPRESOLVE_V4}: only use IPv4 addresses
\item \code{CURL_IPRESOLVE_V6}: only use IPv6 addresses
}
}

\section{CURLOPT_MIME_OPTIONS}{
See \url{https://curl.se/libcurl/c/CURLOPT_MIME_OPTIONS.html}.
\itemize{
\item \code{CURLMIMEOPT_FORMESCAPE}: backslash-escape quotes and backslashes in
multipart form field and file names
}
}

\section{CURLOPT_NETRC}{
Whether to read credentials from the \code{.netrc} file, see
\url{https://curl.se/libcurl/c/CURLOPT_NETRC.html}.
\itemize{
\item \code{CURL_NETRC_IGNORED}: ignore the netrc file (default)
\item \code{CURL_NETRC_OPTIONAL}: use the netrc file, but credentials in the URL
take precedence
\item \code{CURL_NETRC_REQUIRED}: only use the netrc file, ignore credentials in
the URL
}
}

\section{CURLOPT_POSTREDIR}{
Bitmask of redirect codes after which a POST must remain a POST, see
\url{https://curl.se/libcurl/c/CURLOPT_POSTREDIR.html}.
\itemize{
\item \code{CURL_REDIR_POST_301}: keep the POST method after a 301 redirect
\item \code{CURL_REDIR_POST_302}: keep the POST method after a 302 redirect
\item \code{CURL_REDIR_POST_303}: keep the POST method after a 303 redirect
\item \code{CURL_REDIR_POST_ALL}: all of the above
\item \code{CURL_REDIR_GET_ALL}: convert to GET on all redirects (default)
}
}

\section{CURLOPT_PROXYTYPE}{
Type of the proxy set with \code{proxy}, see
\url{https://curl.se/libcurl/c/CURLOPT_PROXYTYPE.html}.
\itemize{
\item \code{CURLPROXY_HTTP}: HTTP proxy (default)
\item \code{CURLPROXY_HTTPS}: HTTPS proxy using HTTP/1.x
\item \code{CURLPROXY_HTTPS2}: HTTPS proxy, attempt HTTP/2
\item \code{CURLPROXY_HTTP_1_0}: HTTP proxy, force HTTP 1.0
\item \code{CURLPROXY_SOCKS4}: SOCKS4 proxy
\item \code{CURLPROXY_SOCKS4A}: SOCKS4a proxy, proxy resolves the hostname
\item \code{CURLPROXY_SOCKS5}: SOCKS5 proxy
\item \code{CURLPROXY_SOCKS5_HOSTNAME}: SOCKS5 proxy, proxy resolves the hostname
}
}

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

\section{CURLOPT_SSH_AUTH_TYPES}{
Bitmask of authentication types for SFTP/SCP connections, see
\url{https://curl.se/libcurl/c/CURLOPT_SSH_AUTH_TYPES.html}.
\itemize{
\item \code{CURLSSH_AUTH_PUBLICKEY}: public/private key files
\item \code{CURLSSH_AUTH_PASSWORD}: password
\item \code{CURLSSH_AUTH_HOST}: host key files
\item \code{CURLSSH_AUTH_KEYBOARD}: keyboard interactive
\item \code{CURLSSH_AUTH_AGENT}: ssh-agent
\item \code{CURLSSH_AUTH_GSSAPI}: gssapi (kerberos, ...)
\item \code{CURLSSH_AUTH_ANY}: any method (default, \code{CURLSSH_AUTH_DEFAULT} is an alias)
\item \code{CURLSSH_AUTH_NONE}: no allowed methods
}
}

\section{CURLOPT_SSL_OPTIONS}{
Bitmask of SSL behavior options, see
\url{https://curl.se/libcurl/c/CURLOPT_SSL_OPTIONS.html}. The same values
apply to \code{proxy_ssl_options}
(\href{https://curl.se/libcurl/c/CURLOPT_PROXY_SSL_OPTIONS.html}{CURLOPT_PROXY_SSL_OPTIONS}).
\itemize{
\item \code{CURLSSLOPT_ALLOW_BEAST}: allow the BEAST SSL vulnerability for
interoperability reasons
\item \code{CURLSSLOPT_NO_REVOKE}: disable certificate revocation checks (Schannel)
\item \code{CURLSSLOPT_NO_PARTIALCHAIN}: do not accept partial certificate chains
\item \code{CURLSSLOPT_REVOKE_BEST_EFFORT}: ignore revocation check failures due
to missing/offline distribution points (Schannel)
\item \code{CURLSSLOPT_NATIVE_CA}: use the operating system's native CA store
\item \code{CURLSSLOPT_AUTO_CLIENT_CERT}: automatically locate and use a client
certificate for authentication (Schannel)
}
}

\section{CURLOPT_SSLVERSION}{
Preferred TLS/SSL version, see
\url{https://curl.se/libcurl/c/CURLOPT_SSLVERSION.html}. The same values apply
to \code{proxy_sslversion}
(\href{https://curl.se/libcurl/c/CURLOPT_PROXY_SSLVERSION.html}{CURLOPT_PROXY_SSLVERSION}).
\itemize{
\item \code{CURL_SSLVERSION_DEFAULT}: default, currently the minimum is TLS v1.0
\item \code{CURL_SSLVERSION_TLSv1}: TLS v1.0 or later
\item \code{CURL_SSLVERSION_TLSv1_0}: TLS v1.0 or later
\item \code{CURL_SSLVERSION_TLSv1_1}: TLS v1.1 or later
\item \code{CURL_SSLVERSION_TLSv1_2}: TLS v1.2 or later
\item \code{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. \code{CURL_SSLVERSION_TLSv1_1 + CURL_SSLVERSION_MAX_TLSv1_2}:
\itemize{
\item \code{CURL_SSLVERSION_MAX_DEFAULT}: the highest supported TLS version
(\code{CURL_SSLVERSION_MAX_NONE} has the same effect)
\item \code{CURL_SSLVERSION_MAX_TLSv1_0}: at most TLS v1.0
\item \code{CURL_SSLVERSION_MAX_TLSv1_1}: at most TLS v1.1
\item \code{CURL_SSLVERSION_MAX_TLSv1_2}: at most TLS v1.2
\item \code{CURL_SSLVERSION_MAX_TLSv1_3}: at most TLS v1.3
}
}

\section{CURLOPT_TIMECONDITION}{
How to compare the \code{timevalue} timestamp, see
\url{https://curl.se/libcurl/c/CURLOPT_TIMECONDITION.html}.
\itemize{
\item \code{CURL_TIMECOND_NONE}: no time condition (default)
\item \code{CURL_TIMECOND_IFMODSINCE}: only transfer if modified since \code{timevalue}
\item \code{CURL_TIMECOND_IFUNMODSINCE}: only transfer if not modified since \code{timevalue}
\item \code{CURL_TIMECOND_LASTMOD}: (FTP only)
}
}

\section{CURLOPT_USE_SSL}{
Request TLS upgrade for FTP, SMTP, POP3 and IMAP transfers, see
\url{https://curl.se/libcurl/c/CURLOPT_USE_SSL.html}.
\itemize{
\item \code{CURLUSESSL_NONE}: do not attempt to use SSL (default)
\item \code{CURLUSESSL_TRY}: try SSL, proceed as normal otherwise
\item \code{CURLUSESSL_CONTROL}: require SSL for the control connection, or fail
\item \code{CURLUSESSL_ALL}: require SSL for all communication, or fail
}
}

\section{CURLOPT_WS_OPTIONS}{
Bitmask with websocket behavior options, see
\url{https://curl.se/libcurl/c/CURLOPT_WS_OPTIONS.html}.
\itemize{
\item \code{CURLWS_RAW_MODE}: deliver raw websocket traffic to the write callback
\item \code{CURLWS_NOAUTOPONG}: disable the automatic reply to PING frames
(libcurl >= 8.14)
}
}

\section{Other symbols}{
The sections above cover the option values supported by \code{\link[=handle_setopt]{handle_setopt()}}.
Use \code{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.
}

\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)

}
\seealso{
\code{\link[=handle_setopt]{handle_setopt()}}
}
