##
+Angle brackets (`<>`) need to be escaped when used in text like `\<` and
+`\>`. This, to ensure that the text renders nicely as markdown.
+
### Headers
The `#` header can be used by non-option files and it produces produces a
The short "single-dash" form of the options, -d for example, may be used with
or without a space between it and its value, although a space is a recommended
-separator. The long "double-dash" form, --data for example, requires a space
+separator. The long double-dash form, --data for example, requires a space
between it and its value.
Short version options that do not need any additional values can be used
In general, all boolean options are enabled with --**option** and yet again
disabled with --**no-**option. That is, you use the same option name but
-prefix it with "no-". However, in this list we mostly only list and show the
+prefix it with `no-`. However, in this list we mostly only list and show the
*--option* version of them.
When --next is used, it resets the parser state and you start again with a
-clean option state, except for the options that are "global". Global options
+clean option state, except for the options that are global. Global options
retain their values and meaning even after --next.
The following options are global: `%GLOBALS`.
meter and response data.
If you want a progress meter for HTTP POST or PUT requests, you need to
-redirect the response output to a file, using shell redirect (>), --output or
-similar.
+redirect the response output to a file, using shell redirect (\>), --output
+or similar.
This does not apply to FTP upload as that operation does not spit out any
response data to the terminal.
-If you prefer a progress "bar" instead of the regular meter, --progress-bar is
+If you prefer a progress bar instead of the regular meter, --progress-bar is
your friend. You can also disable the progress meter completely with the
--silent option.
version 0.9, 1.0, 1.1, 2 and 3 depending on build options and the correct
command line options.
## IMAP(S)
-Using the mail reading protocol, curl can "download" emails for you. With or
+Using the mail reading protocol, curl can download emails for you. With or
without using TLS.
## LDAP(S)
curl can do directory lookups for you, with or without TLS.
## MQTT
-curl supports MQTT version 3. Downloading over MQTT equals "subscribe" to a
-topic while uploading/posting equals "publish" on a topic. MQTT over TLS is
-not supported (yet).
+curl supports MQTT version 3. Downloading over MQTT equals subscribe to a
+topic while uploading/posting equals publish on a topic. MQTT over TLS is not
+supported (yet).
## POP3(S)
Downloading from a pop3 server means getting a mail. With or without using
TLS.
If you provide a URL without a leading **protocol://** scheme, curl guesses
what protocol you want. It then defaults to HTTP but assumes others based on
often-used host name prefixes. For example, for host names starting with
-"ftp." curl assumes you want FTP.
+`ftp.` curl assumes you want FTP.
You can specify any amount of URLs on the command line. They are fetched in a
sequential manner in the specified order unless you use --parallel. You can
<!-- SPDX-License-Identifier: curl -->
# VARIABLES
curl supports command line variables (added in 8.3.0). Set variables with
---variable name=content or --variable name@file (where "file" can be stdin if
+--variable name=content or --variable name@file (where `file` can be stdin if
set to a single dash (-)).
-Variable contents can be expanded in option parameters using "{{name}}" (without
-the quotes) if the option name is prefixed with "--expand-". This gets the
-contents of the variable "name" inserted, or a blank if the name does not
-exist as a variable. Insert "{{" verbatim in the string by prefixing it with a
-backslash, like "\{{".
+Variable contents can be expanded in option parameters using `{{name}}` if the
+option name is prefixed with `--expand-`. This gets the contents of the
+variable `name` inserted, or a blank if the name does not exist as a
+variable. Insert `{{` verbatim in the string by prefixing it with a backslash,
+like `\{{`.
You an access and expand environment variables by first importing them. You
can select to either require the environment variable to be set or you can
# `--abstract-unix-socket`
Connect through an abstract Unix domain socket, instead of using the network.
-Note: netstat shows the path of an abstract socket prefixed with '@', however
-the <path> argument should not have this leading character.
+Note: netstat shows the path of an abstract socket prefixed with `@`, however
+the \<path\> argument should not have this leading character.
private key and the client certificate concatenated. See --cert and --key to
specify them independently.
-In the <certificate> portion of the argument, you must escape the character
-":" as "\:" so that it is not recognized as the password delimiter. Similarly,
+In the \<certificate\> portion of the argument, you must escape the character
+`:` as `\:` so that it is not recognized as the password delimiter. Similarly,
you must escape the double quote character as \" so that it is not recognized
as an escape character.
If curl is built against OpenSSL library, and the engine pkcs11 is available,
then a PKCS#11 URI (RFC 7512) can be used to specify a certificate located in
-a PKCS#11 device. A string beginning with "pkcs11:" is interpreted as a
+a PKCS#11 device. A string beginning with `pkcs11:` is interpreted as a
PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option is set as
-"pkcs11" if none was provided and the --cert-type option is set as "ENG" if
+`pkcs11` if none was provided and the --cert-type option is set as `ENG` if
none was provided.
(iOS and macOS only) If curl is built against Secure Transport, then the
certificate string can either be the name of a certificate/private key in the
system or user keychain, or the path to a PKCS#12-encoded certificate and
private key. If you want to use a file from the current directory, please
-precede it with "./" prefix, in order to avoid confusion with a nickname.
+precede it with `./` prefix, in order to avoid confusion with a nickname.
(Schannel only) Client certificates must be specified by a path expression to
a certificate store. (Loading *PFX* is not supported; you can import it to a
-store first). You can use "<store location>\<store name>\<thumbprint>" to
-refer to a certificate in the system certificates store, for example,
+store first). You can use "\<store location\>\\<store name\>\\<thumbprint\>"
+to refer to a certificate in the system certificates store, for example,
*"CurrentUser\MY\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a"*. Thumbprint is
usually a SHA-1 hex string which you can see in certificate details. Following
store locations are supported: *CurrentUser*, *LocalMachine*,
This posts data, similar to the other --data options with the exception
that this performs URL-encoding.
-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
+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:
## content
# `--dns-interface`
-Tell curl to send outgoing DNS requests through <interface>. This option is a
-counterpart to --interface (which does not affect DNS). The supplied string
-must be an interface name (not an address).
+Tell curl to send outgoing DNS requests through the given interface. This
+option is a counterpart to --interface (which does not affect DNS). The
+supplied string must be an interface name (not an address).
- dns-ipv4-addr
Example:
- --dns-servers 192.168.0.1,192.168.0.2 $URL
+ - --dns-servers 10.0.0.1:53 $URL
---
# `--dns-servers`
-Set the list of DNS servers to be used instead of the system default.
-The list of IP addresses should be separated with commas. Port numbers
-may also optionally be given as *:<port-number>* after each IP
-address.
+Set the list of DNS servers to be used instead of the system default. The list
+of IP addresses should be separated with commas. Port numbers may also
+optionally be given, appended to the IP address separated with a colon.
# `--form-string`
Similar to --form except that the value string for the named parameter is used
-literally. Leading '@' and '<' characters, and the ';type=' string in
-the value have no special meaning. Use this in preference to --form if
-there is any possibility that the string value may accidentally trigger the
-'@' or '<' features of --form.
+literally. Leading @ and \< characters, and the `;type=` string in the value
+have no special meaning. Use this in preference to --form if there is any
+possibility that the string value may accidentally trigger the @ or \<
+features of --form.
This enables uploading of binary files etc. To force the 'content' part to be
a file, prefix the file name with an @ sign. To just get the content part from
-a file, prefix the file name with the symbol <. The difference between @ and <
-is then that @ makes a file get attached in the post as a file upload, while
-the < makes a text field and just get the contents for that text field from a
+a file, prefix the file name with the symbol \<. The difference between @ and
+< is then that @ makes a file get attached in the post as a file upload, while
+the \< makes a text field and just get the contents for that text field from a
file.
Tell curl to read content from stdin instead of a file by using - as
-filename. This goes for both @ and < constructs. When stdin is used, the
+filename. This goes for both @ and \< constructs. When stdin is used, the
contents is buffered in memory first by curl to determine its size and allow a
possible resend. Defining a part's data from a named non-regular file (such as
a named pipe or similar) is not subject to buffering and is instead read at
Reverses the default initiator/listener roles when connecting with FTP. This
option makes curl use active mode. curl then tells the server to connect back
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:
+to setup an IP address and port for it to connect to. \<address\> should be
+one of:
## interface
e.g. **eth0** to specify which interface's IP address you want to use (Unix only)
}
}
- if(!$quote && ($d =~ /^(.*) /)) {
- printf STDERR "$f:$line:%d:ERROR: 2 spaces detected\n",
- length($1);
- return 3;
+ if(!$quote) {
+ if($d =~ /^(.*) /) {
+ printf STDERR "$f:$line:%d:ERROR: 2 spaces detected\n",
+ length($1);
+ return 3;
+ }
+ elsif($d =~ /[^\\][\<\>]/) {
+ print STDERR "$f:$line:1:WARN: un-escaped < or > used\n";
+ return 3;
+ }
}
+ # convert backslash-'<' or '> to just the second character
+ $d =~ s/\\([<<])/$1/g;
# quote minuses in the output
$d =~ s/([^\\])-/$1\\-/g;
# replace single quotes
# `--output`
-Write output to <file> instead of stdout. If you are using {} or [] to fetch
-multiple documents, you should quote the URL and you can use '#' followed by a
-number in the <file> specifier. That variable is replaced with the current
-string for the URL being fetched. Like in:
+Write output to the given file instead of stdout. If you are using globbing to
+fetch multiple documents, you should quote the URL and you can use `#`
+followed by a number in the file name. That variable is then replaced with the
+current string for the URL being fetched. Like in:
curl "http://{one,two}.example.com" -o "file_#1.txt"
## 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
+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)
## chgrp group 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
+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)
## pwd
c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
SPDX-License-Identifier: curl
Long: raw
-Help: Do HTTP "raw"; no transfer decoding
+Help: Do HTTP raw; no transfer decoding
Added: 7.16.2
Protocols: HTTP
Category: http
# `--referer`
-Sends the "Referrer Page" information to the HTTP server. This can also be set
-with the --header flag of course. When used with --location you can append
-";auto" to the --referer URL to make curl automatically set the previous URL
-when it follows a Location: header. The ";auto" string can be used alone,
-even if you do not set an initial --referer.
+Sends the referrer URL in the HTTP request. This can also be set with the
+--header flag of course. When used with --location you can append `;auto`" to
+the --referer URL to make curl automatically set the previous URL when it
+follows a Location: header. The `;auto` string can be used alone, even if you
+do not set an initial --referer.
There is no attempt to decode %-sequences (yet) in the provided file name, so
this option may provide you with rather unexpected file names.
-This feature uses the name from the "filename" field, it does not yet support
-the "filename*" field (filenames with explicit character sets).
+This feature uses the name from the `filename` field, it does not yet support
+the `filename*` field (filenames with explicit character sets).
**WARNING**: Exercise judicious use of this option, especially on Windows. A
rogue server could send you the name of a DLL or other file that could be
# `--request-target`
-Tells curl to use an alternative "target" (path) instead of using the path as
+Tells curl to use an alternative target (path) instead of using the path as
provided in the URL. Particularly useful when wanting to issue HTTP requests
without leading slash or other data that does not follow the regular URL
pattern, like "OPTIONS *".
transfers as close as possible to how they were started, but this is not
possible with redirected input or output. For example, before retrying it
removes output data from a failed partial transfer that was written to an
-output file. However this is not true of data redirected to a | pipe or >
+output file. However this is not true of data redirected to a | pipe or \>
file, which are not reset. We strongly suggest you do not parse or record
output via redirect in combination with this option, since you may receive
duplicate data.
# `--tftp-blksize`
-Set the TFTP **BLKSIZE** option (must be >512). This is the block size that
-curl tries to use when transferring data to or from a TFTP server. By
-default 512 bytes are used.
+Set the TFTP **BLKSIZE** option (must be 512 or larger). This is the block
+size that curl tries to use when transferring data to or from a TFTP
+server. By default 512 bytes are used.
# `--time-cond`
Request a file that has been modified later than the given time and date, or
-one that has been modified before that time. The <date expression> can be all
-sorts of date strings or if it does not match any internal ones, it is taken as
-a filename and tries to get the modification date (mtime) from <file>
-instead. See the *curl_getdate(3)* man pages for date expression details.
+one that has been modified before that time. The date expression can be all
+sorts of date strings or if it does not match any internal ones, it is treated
+as a filename and curl tries to get the modification date (mtime) from that
+file instead. See the *curl_getdate(3)* man pages for date expression details.
Start the date expression with a dash (-) to make it request for a document
that is older than the given date/time, default is a document that is newer
# `--tlsauthtype`
-Set TLS authentication type. Currently, the only supported option is "SRP",
+Set TLS authentication type. Currently, the only supported option is `SRP`,
for TLS-SRP (RFC 5054). If --tlsuser and --tlspassword are specified but
---tlsauthtype is not, then this option defaults to "SRP". This option works
+--tlsauthtype is not, then this option defaults to `SRP`. This option works
only if the underlying libcurl is built with TLS-SRP support, which requires
OpenSSL or GnuTLS with TLS-SRP support.
# `--trace-ascii`
Enables a full trace dump of all incoming and outgoing data, including
-descriptive information, to the given output file. Use "-" as filename to have
+descriptive information, to the given output file. Use `-` as filename to have
the output sent to stdout.
This is similar to --trace, but leaves out the hex part and only shows the
detailed output can be made available from. Names are case-insensitive.
Specify 'all' to enable all trace components.
-In addition to trace component names, specify "ids" and "time" to
-avoid extra --trace-ids or --trace-time parameters.
+In addition to trace component names, specify `ids` and `time` to avoid extra
+--trace-ids or --trace-time parameters.
See the *curl_global_trace(3)* man page for more details.
on the left side of any slash (/) or backslash (\) used in the file name and
only appends what is on the right side of the rightmost such character.
-Use the file name "-" (a single dash) to use stdin instead of a given file.
-Alternately, the file name "." (a single period) may be specified instead of
-"-" to use stdin in non-blocking mode to allow reading server output while
+Use the file name `-` (a single dash) to use stdin instead of a given file.
+Alternately, the file name `.` (a single period) may be specified instead of
+`-` to use stdin in non-blocking mode to allow reading server output while
stdin is being uploaded.
If this option is used with a HTTP(S) URL, the PUT method is used.
You can specify one --upload-file for each URL on the command line. Each
--upload-file + URL pair specifies what to upload and to where. curl also
-supports "globbing" of the --upload-file argument, meaning that you can upload
+supports globbing of the --upload-file argument, meaning that you can upload
multiple files to a single URL by using the same URL globbing style supported
in the URL.
Specify a URL to fetch. This option is mostly handy when you want to specify
URL(s) in a config file.
-If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)
+If the given URL is missing a scheme name (such as `http://` or `ftp://` etc)
then curl makes a guess based on the host. If the outermost subdomain name
matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol is used,
otherwise HTTP is used. Guessing can be avoided by providing a full URL
To control where this URL is written, use the --output or the --remote-name
options.
-**WARNING**: On Windows, particular file:// accesses can be converted to
+**WARNING**: On Windows, particular `file://` accesses can be converted to
network accesses by the operating system. Beware!
# `--use-ascii`
Enable ASCII transfer. For FTP, this can also be enforced by using a URL that
-ends with ";type=A". This option causes data sent to stdout to be in text mode
+ends with `;type=A`. This option causes data sent to stdout to be in text mode
for win32 systems.
# `--variable`
-Set a variable with "name=content" or "name@file" (where "file" can be stdin
-if set to a single dash (-)). The name is a case sensitive identifier that
+Set a variable with `name=content` or `name@file` (where `file` can be stdin
+if set to a single dash (`-`)). The name is a case sensitive identifier that
must consist of no other letters than a-z, A-Z, 0-9 or underscore. The
specified content is then associated with this identifier.
Setting the same variable name again overwrites the old contents with the new.
The contents of a variable can be referenced in a later command line option
-when that option name is prefixed with "--expand-", and the name is used as
-"{{name}}" (without the quotes).
+when that option name is prefixed with `--expand-`, and the name is used as
+`{{name}}`.
--variable can import environment variables into the name space. Opt to either
require the environment variable to be set or provide a default value for the
variable in case it is not already set.
---variable %name imports the variable called 'name' but exits with an error if
+--variable %name imports the variable called `name` but exits with an error if
that environment variable is not already set. To provide a default value if
the environment variable is not set, use --variable %name=content or
--variable %name@content. Note that on some systems - but not all -
# `--verbose`
Makes curl verbose during the operation. Useful for debugging and seeing
-what's going on "under the hood". A line starting with '>' means "header data"
-sent by curl, '<' means "header data" received by curl that is hidden in
-normal cases, and a line starting with '*' means additional info provided by
-curl.
+what's going on under the hood. A line starting with \> means header data sent
+by curl, \< means header data received by curl that is hidden in normal cases,
+and a line starting with * means additional info provided by curl.
If you only want HTTP headers in the output, --include or --dump-header might
be more suitable options.
output following that instruction is then written to that file. More than one
*%output{}* instruction can be specified in the same write-out argument. If
the file name cannot be created, curl leaves the output destination to the one
-used prior to the *%output{}* instruction. Use *%output{>>name}* to append
+used prior to the *%output{}* instruction. Use *%output{\>\>name}* to append
data to an existing file.
**NOTE:**
"Request rate for serial transfers",
CURLHELP_CONNECTION},
{" --raw",
- "Do HTTP \"raw\"; no transfer decoding",
+ "Do HTTP raw; no transfer decoding",
CURLHELP_HTTP},
{"-e, --referer <URL>",
"Referrer URL",
projects / thirdparty / curl.git / commitdiff
