To make the editing easier. To write and to read.
Closes #12667
To be CGI-compliant, the <data> part should begin with a *name* followed
by a separator and a content specification. The <data> part can be passed to
curl using one of the following syntaxes:
-.RS
-.IP "content"
+
+## content
This makes curl URL-encode the content and pass that on. Just be careful
so that the content does not contain any = or @ symbols, as that makes
the syntax match one of the other cases below!
-.IP "=content"
+
+## =content
This makes curl URL-encode the content and pass that on. The preceding =
symbol is not included in the data.
-.IP "name=content"
+
+## name=content
This makes curl URL-encode the content part and pass that on. Note that
the name part is expected to be URL-encoded already.
-.IP "@filename"
+
+## @filename
This makes curl load data from the given file (including any newlines),
URL-encode that data and pass it on in the POST.
-.IP "name@filename"
+
+## name@filename
This makes curl load data from the given file (including any newlines),
URL-encode that data and pass it on in the POST. The name part gets an equal
sign appended, resulting in *name=urlencoded-file-content*. Note that the
name is expected to be URL-encoded already.
-.RE
-.IP
---
Set LEVEL to tell the server what it is allowed to delegate when it
comes to user credentials.
-.RS
-.IP "none"
+
+## none
Do not allow any delegation.
-.IP "policy"
+
+## policy
Delegates if and only if the OK-AS-DELEGATE flag is set in the Kerberos
service ticket, which is a matter of realm policy.
-.IP "always"
+
+## always
Unconditionally allow the server to delegate.
-.RE
-.IP
---
Control what method curl should use to reach a file on an FTP(S)
server. The method argument should be one of the following alternatives:
-.RS
-.IP multicwd
+
+## multicwd
curl does a single CWD operation for each path part in the given URL. For deep
hierarchies this means many commands. This is how RFC 1738 says it should
be done. This is the default but the slowest behavior.
-.IP nocwd
+
+## nocwd
curl does no CWD at all. curl does SIZE, RETR, STOR etc and give a full
path to the server for all these commands. This is the fastest behavior.
-.IP singlecwd
+
+## singlecwd
curl does one CWD with the full target directory and then operates on the file
"normally" (like in the multicwd case). This is somewhat more standards
compliant than 'nocwd' but without the full penalty of 'multicwd'.
-.RE
-.IP
to the client's specified address and port, while passive mode asks the server
to setup an IP address and port for it to connect to. <address> should be one
of:
-.RS
-.IP interface
-e.g. "eth0" to specify which interface's IP address you want to use (Unix only)
-.IP "IP address"
-e.g. "192.168.10.1" to specify the exact IP address
-.IP "host name"
-e.g. "my.host.domain" to specify the machine
-.IP "-"
+
+## interface
+e.g. **eth0** to specify which interface's IP address you want to use (Unix only)
+
+## IP address
+e.g. **192.168.10.1** to specify the exact IP address
+
+## host name
+e.g. **my.host.domain** to specify the machine
+
+## -
make curl pick the same IP address that is already used for the control
-connection
-.RE
-.IP
+connection. This is the recommended choice.
+
+##
Disable the use of PORT with --ftp-pasv. Disable the attempt to use the EPRT
command instead of PORT by using --disable-eprt. EPRT is really PORT++.
Tells curl to limit what protocols it may use for transfers. Protocols are
evaluated left to right, are comma separated, and are each a protocol name or
'all', optionally prefixed by zero or more modifiers. Available modifiers are:
-.RS
-.IP +
+
+## +
Permit this protocol in addition to protocols already permitted (this is
the default if no modifier is used).
-.IP -
+
+## -
Deny this protocol, removing it from the list of protocols already permitted.
-.IP =
+
+## =
Permit only this protocol (ignoring the list already permitted), though
subject to later modification by subsequent entries in the comma separated
list.
-.RE
-.IP
+
+##
+
For example: --proto -ftps uses the default protocols, but disables ftps
--proto -all,https,+http only enables http and https
itself before sending them to the server. File names may be quoted
shell-style to embed spaces or special characters. Following is the list of
all supported SFTP quote commands:
-.RS
-.IP "atime date file"
+
+## atime date file
The atime command sets the last access time of the file named by the file
operand. The <date expression> can be all sorts of date strings, see the
*curl_getdate(3)* man page for date expression details. (Added in 7.73.0)
-.IP "chgrp group file"
+
+## chgrp group file
The chgrp command sets the group ID of the file named by the file operand to
the group ID specified by the group operand. The group operand is a decimal
integer group ID.
-.IP "chmod mode file"
+
+## chmod mode file
The chmod command modifies the file mode bits of the specified file. The
mode operand is an octal integer mode number.
-.IP "chown user file"
+
+## chown user file
The chown command sets the owner of the file named by the file operand to the
user ID specified by the user operand. The user operand is a decimal
integer user ID.
-.IP "ln source_file target_file"
+
+## ln source_file target_file
The ln and symlink commands create a symbolic link at the target_file location
pointing to the source_file location.
-.IP "mkdir directory_name"
+
+## mkdir directory_name
The mkdir command creates the directory named by the directory_name operand.
-.IP "mtime date file"
+
+## mtime date file
The mtime command sets the last modification time of the file named by the
file operand. The <date expression> can be all sorts of date strings, see the
*curl_getdate(3)* man page for date expression details. (Added in 7.73.0)
-.IP "pwd"
+
+## pwd
The pwd command returns the absolute path name of the current working directory.
-.IP "rename source target"
+
+## rename source target
The rename command renames the file or directory named by the source
operand to the destination path named by the target operand.
-.IP "rm file"
+
+## rm file
The rm command removes the file specified by the file operand.
-.IP "rmdir directory"
+
+## rmdir directory
The rmdir command removes the directory entry specified by the directory
operand, provided it is empty.
-.IP "symlink source_file target_file"
+
+## symlink source_file target_file
See ln.
-.RE
-.IP
---
Retrieve a byte range (i.e. a partial document) from an HTTP/1.1, FTP or SFTP
server or a local FILE. Ranges can be specified in a number of ways.
-.RS
-.IP 0-499
+
+## 0-499
specifies the first 500 bytes
-.IP 500-999
+
+## 500-999
specifies the second 500 bytes
-.IP -500
+
+## -500
specifies the last 500 bytes
-.IP 9500-
+
+## 9500-
specifies the bytes from offset 9500 and forward
-.IP 0-0,-1
+
+## 0-0,-1
specifies the first and last byte only(*)(HTTP)
-.IP 100-199,500-599
+
+## 100-199,500-599
specifies two separate 100-byte ranges(*) (HTTP)
-.RE
-.IP
-(*) = NOTE that this causes the server to reply with a multipart response,
-which is returned as-is by curl! Parsing or otherwise transforming this
-response is the responsibility of the caller.
+
+##
+
+(*) = NOTE that these make the server reply with a multipart response, which
+is returned as-is by curl! Parsing or otherwise transforming this response is
+the responsibility of the caller.
Only digit characters (0-9) are valid in the 'start' and 'stop' fields of the
'start-stop' range syntax. If a non-digit character is given in the range, the
curl passes on the verbatim string you give it its the request without any
filter or other safe guards. That includes white space and control characters.
-.RS
-.IP HTTP
+
+## HTTP
Specifies a custom request method to use when communicating with the HTTP
server. The specified request method is used instead of the method otherwise
used (which defaults to *GET*). Read the HTTP 1.1 specification for details
if you for example use --location may cause unintended side-effects when curl
does not change request method according to the HTTP 30x response codes - and
similar.
-.IP FTP
+
+## FTP
Specifies a custom FTP command to use instead of *LIST* when doing file lists
with FTP.
-.IP POP3
+
+## POP3
Specifies a custom POP3 command to use instead of *LIST* or *RETR*.
(Added in 7.26.0)
-.IP IMAP
+
+## IMAP
Specifies a custom IMAP command to use instead of *LIST*. (Added in 7.30.0)
-.IP SMTP
+
+## SMTP
Specifies a custom SMTP command to use instead of *HELP* or **VRFY**. (Added in 7.34.0)
-.RE
-.IP
---
Pass options to the telnet protocol. Supported options are:
-.RS
-.IP "TTYPE=<term>"
+## TTYPE=<term>
Sets the terminal type.
-.IP "XDISPLOC=<X display>"
+
+## XDISPLOC=<X display>
Sets the X display location.
-.IP "NEW_ENV=<var,val>"
+
+## NEW_ENV=<var,val>
Sets an environment variable.
-.RE
-.IP
If the connection is done without TLS, this option has no effect. This
includes QUIC-using (HTTP/3) transfers.
-.RS
-.IP "default"
+## default
Use up to recommended TLS version.
-.IP "1.0"
+
+## 1.0
Use up to TLSv1.0.
-.IP "1.1"
+
+## 1.1
Use up to TLSv1.1.
-.IP "1.2"
+
+## 1.2
Use up to TLSv1.2.
-.IP "1.3"
+
+## 1.3
Use up to TLSv1.3.
-.RE
-.IP
error.
Available functions:
-.RS
-.IP trim
+
+## trim
removes all leading and trailing white space.
-.IP json
+
+## json
outputs the content using JSON string quoting rules.
-.IP url
+
+## url
shows the content URL (percent) encoded.
-.IP b64
+
+## b64
expands the variable base64 encoded
-.RE
-.IP
The fourth line (starts with "Features:") shows specific features libcurl
reports to offer. Available features include:
-.RS
-.IP "alt-svc"
+
+## alt-svc
Support for the Alt-Svc: header is provided.
-.IP "AsynchDNS"
+
+## AsynchDNS
This curl uses asynchronous name resolves. Asynchronous name resolves can be
done using either the c-ares or the threaded resolver backends.
-.IP "brotli"
+
+## brotli
Support for automatic brotli compression over HTTP(S).
-.IP "CharConv"
+
+## CharConv
curl was built with support for character set conversions (like EBCDIC)
-.IP "Debug"
+
+## Debug
This curl uses a libcurl built with Debug. This enables more error-tracking
and memory debugging etc. For curl-developers only!
-.IP "gsasl"
+
+## gsasl
The built-in SASL authentication includes extensions to support SCRAM because
libcurl was built with libgsasl.
-.IP "GSS-API"
+
+## GSS-API
GSS-API is supported.
-.IP "HSTS"
+
+## HSTS
HSTS support is present.
-.IP "HTTP2"
+
+## HTTP2
HTTP/2 support has been built-in.
-.IP "HTTP3"
+
+## HTTP3
HTTP/3 support has been built-in.
-.IP "HTTPS-proxy"
+
+## HTTPS-proxy
This curl is built to support HTTPS proxy.
-.IP "IDN"
+
+## IDN
This curl supports IDN - international domain names.
-.IP "IPv6"
+
+## IPv6
You can use IPv6 with this.
-.IP "Kerberos"
+
+## Kerberos
Kerberos V5 authentication is supported.
-.IP "Largefile"
+
+## Largefile
This curl supports transfers of large files, files larger than 2GB.
-.IP "libz"
+
+## libz
Automatic decompression (via gzip, deflate) of compressed files over HTTP is
supported.
-.IP "MultiSSL"
+
+## MultiSSL
This curl supports multiple TLS backends.
-.IP "NTLM"
+
+## NTLM
NTLM authentication is supported.
-.IP "NTLM_WB"
+
+## NTLM_WB
NTLM delegation to winbind helper is supported.
-.IP "PSL"
+
+## PSL
PSL is short for Public Suffix List and means that this curl has been built
with knowledge about "public suffixes".
-.IP "SPNEGO"
+
+## SPNEGO
SPNEGO authentication is supported.
-.IP "SSL"
+
+## SSL
SSL versions of various protocols are supported, such as HTTPS, FTPS, POP3S
and so on.
-.IP "SSPI"
+
+## SSPI
SSPI is supported.
-.IP "TLS-SRP"
+
+## TLS-SRP
SRP (Secure Remote Password) authentication is supported for TLS.
-.IP "TrackMemory"
+
+## TrackMemory
Debug memory tracking is supported.
-.IP "Unicode"
+
+## Unicode
Unicode support on Windows.
-.IP "UnixSockets"
+
+## UnixSockets
Unix sockets support is provided.
-.IP "zstd"
+
+## zstd
Automatic decompression (via zstd) of compressed files over HTTP is supported.
-.RE
-.IP
the % cannot be escaped and unintended expansion is possible.
The variables available are:
-.RS
-.IP certs
+
+## certs
Output the certificate chain with details. Supported only by the OpenSSL,
GnuTLS, Schannel and Secure Transport backends. (Added in 7.88.0)
-.IP content_type
+
+## content_type
The Content-Type of the requested document, if there was any.
-.IP errormsg
+
+## errormsg
The error message. (Added in 7.75.0)
-.IP exitcode
+
+## exitcode
The numerical exit code of the transfer. (Added in 7.75.0)
-.IP filename_effective
+
+## filename_effective
The ultimate filename that curl writes out to. This is only meaningful if curl
is told to write to a file with the --remote-name or --output
option. It's most useful in combination with the --remote-header-name
option. (Added in 7.26.0)
-.IP ftp_entry_path
+
+## ftp_entry_path
The initial path curl ended up in when logging on to the remote FTP
server. (Added in 7.15.4)
-.IP header_json
+
+## header_json
A JSON object with all HTTP response headers from the recent transfer. Values
are provided as arrays, since in the case of multiple headers there can be
multiple values. (Added in 7.83.0)
The header names provided in lowercase, listed in order of appearance over the
wire. Except for duplicated headers. They are grouped on the first occurrence
of that header, each value is presented in the JSON array.
-.IP http_code
+
+## http_code
The numerical response code that was found in the last retrieved HTTP(S) or
FTP(s) transfer.
-.IP http_connect
+
+## http_connect
The numerical code that was found in the last response (from a proxy) to a
curl CONNECT request. (Added in 7.12.4)
-.IP http_version
+
+## http_version
The http version that was effectively used. (Added in 7.50.0)
-.IP json
+
+## json
A JSON object with all available keys. (Added in 7.70.0)
-.IP local_ip
+
+## local_ip
The IP address of the local end of the most recently done connection - can be
either IPv4 or IPv6. (Added in 7.29.0)
-.IP local_port
+
+## local_port
The local port number of the most recently done connection. (Added in 7.29.0)
-.IP method
+
+## method
The http method used in the most recent HTTP request. (Added in 7.72.0)
-.IP num_certs
+
+## num_certs
Number of server certificates received in the TLS handshake. Supported only by
the OpenSSL, GnuTLS, Schannel and Secure Transport backends.
(Added in 7.88.0)
-.IP num_connects
+
+## num_connects
Number of new connects made in the recent transfer. (Added in 7.12.3)
-.IP num_headers
+
+## num_headers
The number of response headers in the most recent request (restarted at each
redirect). Note that the status line IS NOT a header. (Added in 7.73.0)
-.IP num_redirects
+
+## num_redirects
Number of redirects that were followed in the request. (Added in 7.12.3)
-.IP onerror
+
+## onerror
The rest of the output is only shown if the transfer returned a non-zero error.
(Added in 7.75.0)
-.IP "proxy_ssl_verify_result"
+
+## "proxy_ssl_verify_result"
The result of the HTTPS proxy's SSL peer certificate verification that was
requested. 0 means the verification was successful. (Added in 7.52.0)
-.IP redirect_url
+
+## redirect_url
When an HTTP request was made without --location to follow redirects (or when
--max-redirs is met), this variable shows the actual URL a redirect
*would* have gone to. (Added in 7.18.2)
-.IP referer
+
+## referer
The Referer: header, if there was any. (Added in 7.76.0)
-.IP remote_ip
+
+## remote_ip
The remote IP address of the most recently done connection - can be either
IPv4 or IPv6. (Added in 7.29.0)
-.IP remote_port
+
+## remote_port
The remote port number of the most recently done connection. (Added in 7.29.0)
-.IP response_code
+
+## response_code
The numerical response code that was found in the last transfer (formerly
known as "http_code"). (Added in 7.18.2)
-.IP scheme
+
+## scheme
The URL scheme (sometimes called protocol) that was effectively used. (Added in 7.52.0)
-.IP size_download
+
+## size_download
The total amount of bytes that were downloaded. This is the size of the
body/data that was transferred, excluding headers.
-.IP size_header
+
+## size_header
The total amount of bytes of the downloaded headers.
-.IP size_request
+
+## size_request
The total amount of bytes that were sent in the HTTP request.
-.IP size_upload
+
+## size_upload
The total amount of bytes that were uploaded. This is the size of the
body/data that was transferred, excluding headers.
-.IP speed_download
+
+## speed_download
The average download speed that curl measured for the complete download. Bytes
per second.
-.IP speed_upload
+
+## speed_upload
The average upload speed that curl measured for the complete upload. Bytes per
second.
-.IP ssl_verify_result
+
+## ssl_verify_result
The result of the SSL peer certificate verification that was requested. 0
means the verification was successful. (Added in 7.19.0)
-.IP stderr
+
+## stderr
From this point on, the --write-out output is written to standard
error. (Added in 7.63.0)
-.IP stdout
+
+## stdout
From this point on, the --write-out output is written to standard output.
This is the default, but can be used to switch back after switching to stderr.
(Added in 7.63.0)
-.IP time_appconnect
+
+## time_appconnect
The time, in seconds, it took from the start until the SSL/SSH/etc
connect/handshake to the remote host was completed. (Added in 7.19.0)
-.IP time_connect
+
+## time_connect
The time, in seconds, it took from the start until the TCP connect to the
remote host (or proxy) was completed.
-.IP time_namelookup
+
+## time_namelookup
The time, in seconds, it took from the start until the name resolving was
completed.
-.IP time_pretransfer
+
+## time_pretransfer
The time, in seconds, it took from the start until the file transfer was just
about to begin. This includes all pre-transfer commands and negotiations that
are specific to the particular protocol(s) involved.
-.IP time_redirect
+
+## time_redirect
The time, in seconds, it took for all redirection steps including name lookup,
connect, pretransfer and transfer before the final transaction was
started. time_redirect shows the complete execution time for multiple
redirections. (Added in 7.12.3)
-.IP time_starttransfer
+
+## time_starttransfer
The time, in seconds, it took from the start until the first byte is received.
This includes time_pretransfer and also the time the server needed to calculate
the result.
-.IP time_total
+
+## time_total
The total time, in seconds, that the full operation lasted.
-.IP url
+
+## url
The URL that was fetched. (Added in 7.75.0)
-.IP url.scheme
+
+## url.scheme
The scheme part of the URL that was fetched. (Added in 8.1.0)
-.IP url.user
+
+## url.user
The user part of the URL that was fetched. (Added in 8.1.0)
-.IP url.password
+
+## url.password
The password part of the URL that was fetched. (Added in 8.1.0)
-.IP url.options
+
+## url.options
The options part of the URL that was fetched. (Added in 8.1.0)
-.IP url.host
+
+## url.host
The host part of the URL that was fetched. (Added in 8.1.0)
-.IP url.port
+
+## url.port
The port number of the URL that was fetched. If no port number was specified,
but the URL scheme is known, that scheme's default port number is
shown. (Added in 8.1.0)
-.IP url.path
+
+## url.path
The path part of the URL that was fetched. (Added in 8.1.0)
-.IP url.query
+
+## url.query
The query part of the URL that was fetched. (Added in 8.1.0)
-.IP url.fragment
+
+## url.fragment
The fragment part of the URL that was fetched. (Added in 8.1.0)
-.IP url.zoneid
+
+## url.zoneid
The zone id part of the URL that was fetched. (Added in 8.1.0)
-.IP urle.scheme
+
+## urle.scheme
The scheme part of the effective (last) URL that was fetched. (Added in 8.1.0)
-.IP urle.user
+
+## urle.user
The user part of the effective (last) URL that was fetched. (Added in 8.1.0)
-.IP urle.password
+
+## urle.password
The password part of the effective (last) URL that was fetched. (Added in 8.1.0)
-.IP urle.options
+
+## urle.options
The options part of the effective (last) URL that was fetched. (Added in 8.1.0)
-.IP urle.host
+
+## urle.host
The host part of the effective (last) URL that was fetched. (Added in 8.1.0)
-.IP urle.port
+
+## urle.port
The port number of the effective (last) URL that was fetched. If no port
number was specified, but the URL scheme is known, that scheme's default port
number is shown. (Added in 8.1.0)
-.IP urle.path
+
+## urle.path
The path part of the effective (last) URL that was fetched. (Added in 8.1.0)
-.IP urle.query
+
+## urle.query
The query part of the effective (last) URL that was fetched. (Added in 8.1.0)
-.IP urle.fragment
+
+## urle.fragment
The fragment part of the effective (last) URL that was fetched. (Added in 8.1.0)
-.IP urle.zoneid
+
+## urle.zoneid
The zone id part of the effective (last) URL that was fetched. (Added in 8.1.0)
-.IP urlnum
+
+## urlnum
The URL index number of this transfer, 0-indexed. Unglobbed URLs share the
same index number as the origin globbed URL. (Added in 7.75.0)
-.IP url_effective
+
+## url_effective
The URL that was fetched last. This is most meaningful if you have told curl
to follow location: headers.
-.RE
-.IP
projects / thirdparty / curl.git / commitdiff
