mirror of
https://github.com/curl/curl.git
synced 2024-11-21 01:16:58 +08:00
curl.1: shorten lines, avoid referring to libcurl instead of curl
This commit is contained in:
Daniel Stenberg
parent
4dcde5aa3d
commit
b8983aa309
170
docs/curl.1
170
docs/curl.1
@ -79,14 +79,14 @@ curl will do its best to use what you pass to it as a URL. It is not trying to
|
||||
validate it as a syntactically correct URL by any means but is instead
|
||||
\fBvery\fP liberal with what it accepts.
|
||||
|
||||
Curl will attempt to re-use connections for multiple file transfers, so that
|
||||
curl will attempt to re-use connections for multiple file transfers, so that
|
||||
getting many files from the same server will not do multiple connects /
|
||||
handshakes. This improves speed. Of course this is only done on files
|
||||
specified on a single command line and cannot be used between separate curl
|
||||
invokes.
|
||||
.SH "PROGRESS METER"
|
||||
curl normally displays a progress meter during operations, indicating the amount
|
||||
of transferred data, transfer speeds and estimated time left, etc.
|
||||
curl normally displays a progress meter during operations, indicating the
|
||||
amount of transferred data, transfer speeds and estimated time left, etc.
|
||||
|
||||
curl displays this data to the terminal by default, so if you invoke curl to
|
||||
do an operation and it is about to write data to the terminal, it
|
||||
@ -125,13 +125,13 @@ Forces curl to use SSL version 2 when negotiating with a remote SSL server.
|
||||
(SSL)
|
||||
Forces curl to use SSL version 3 when negotiating with a remote SSL server.
|
||||
.IP "-4, --ipv4"
|
||||
If libcurl is capable of resolving an address to multiple IP versions (which
|
||||
it is if it is IPv6-capable), this option tells libcurl to resolve names to
|
||||
IPv4 addresses only.
|
||||
If curl is capable of resolving an address to multiple IP versions (which it
|
||||
is if it is IPv6-capable), this option tells curl to resolve names to IPv4
|
||||
addresses only.
|
||||
.IP "-6, --ipv6"
|
||||
If libcurl is capable of resolving an address to multiple IP versions (which
|
||||
it is if it is IPv6-capable), this option tells libcurl to resolve names to
|
||||
IPv6 addresses only.
|
||||
If curl is capable of resolving an address to multiple IP versions (which it
|
||||
is if it is IPv6-capable), this option tells curl to resolve names to IPv6
|
||||
addresses only.
|
||||
.IP "-a, --append"
|
||||
(FTP/SFTP) When used in an upload, this will tell curl to append to the target
|
||||
file instead of overwriting it. If the file doesn't exist, it will be created.
|
||||
@ -185,12 +185,12 @@ this option is usually pointless, unless you use it to override a previously
|
||||
set option that sets a different authentication method (such as \fI--ntlm\fP,
|
||||
\fI--digest\fP, or \fI--negotiate\fP).
|
||||
.IP "-c, --cookie-jar <file name>"
|
||||
(HTTP) Specify to which file you want curl to write all cookies after a completed
|
||||
operation. Curl writes all cookies previously read from a specified file as
|
||||
well as all cookies received from remote server(s). If no cookies are known,
|
||||
no file will be written. The file will be written using the Netscape cookie
|
||||
file format. If you set the file name to a single dash, "-", the cookies will
|
||||
be written to stdout.
|
||||
(HTTP) Specify to which file you want curl to write all cookies after a
|
||||
completed operation. Curl writes all cookies previously read from a specified
|
||||
file as well as all cookies received from remote server(s). If no cookies are
|
||||
known, no file will be written. The file will be written using the Netscape
|
||||
cookie file format. If you set the file name to a single dash, "-", the
|
||||
cookies will be written to stdout.
|
||||
|
||||
This command line option will activate the cookie engine that makes curl
|
||||
record and use cookies. Another way to activate it is to use the \fI-b,
|
||||
@ -218,13 +218,13 @@ If this option is used several times, the last one will be used.
|
||||
must specify valid ciphers. Read up on SSL cipher list details on this URL:
|
||||
\fIhttp://www.openssl.org/docs/apps/ciphers.html\fP
|
||||
|
||||
NSS ciphers are done differently than OpenSSL and GnuTLS. The full list of
|
||||
NSS ciphers is in the NSSCipherSuite entry at this URL:
|
||||
NSS ciphers are done differently than OpenSSL and GnuTLS. The full list of NSS
|
||||
ciphers is in the NSSCipherSuite entry at this URL:
|
||||
\fIhttp://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives\fP
|
||||
|
||||
If this option is used several times, the last one will be used.
|
||||
.IP "--compressed"
|
||||
(HTTP) Request a compressed response using one of the algorithms libcurl
|
||||
(HTTP) Request a compressed response using one of the algorithms curl
|
||||
supports, and save the uncompressed document. If this option is used and the
|
||||
server sends an unsupported encoding, curl will report an error.
|
||||
.IP "--connect-timeout <seconds>"
|
||||
@ -234,10 +234,10 @@ of no more use. See also the \fI-m, --max-time\fP option.
|
||||
|
||||
If this option is used several times, the last one will be used.
|
||||
.IP "--create-dirs"
|
||||
When used in conjunction with the \fI-o\fP option, curl will create the necessary
|
||||
local directory hierarchy as needed. This option creates the dirs mentioned
|
||||
with the \fI-o\fP option, nothing else. If the \fI-o\fP file name uses no dir or if the
|
||||
dirs it mentions already exist, no dir will be created.
|
||||
When used in conjunction with the \fI-o\fP option, curl will create the
|
||||
necessary local directory hierarchy as needed. This option creates the dirs
|
||||
mentioned with the \fI-o\fP option, nothing else. If the \fI-o\fP file name
|
||||
uses no dir or if the dirs it mentions already exist, no dir will be created.
|
||||
|
||||
To create remote directories when using FTP or SFTP, try
|
||||
\fI--ftp-create-dirs\fP.
|
||||
@ -336,10 +336,10 @@ service ticket, which is a matter of realm policy.
|
||||
Unconditionally allow the server to delegate.
|
||||
.RE
|
||||
.IP "--digest"
|
||||
(HTTP) Enables HTTP Digest authentication. This is an authentication scheme that
|
||||
prevents the password from being sent over the wire in clear text. Use this in
|
||||
combination with the normal \fI-u, --user\fP option to set user name and
|
||||
password. See also \fI--ntlm\fP, \fI--negotiate\fP and \fI--anyauth\fP for
|
||||
(HTTP) Enables HTTP Digest authentication. This is an authentication scheme
|
||||
that prevents the password from being sent over the wire in clear text. Use
|
||||
this in combination with the normal \fI-u, --user\fP option to set user name
|
||||
and password. See also \fI--ntlm\fP, \fI--negotiate\fP and \fI--anyauth\fP for
|
||||
related options.
|
||||
|
||||
If this option is used several times, only the first one is used.
|
||||
@ -347,9 +347,9 @@ If this option is used several times, only the first one is used.
|
||||
(FTP) Tell curl to disable the use of the EPRT and LPRT commands when doing
|
||||
active FTP transfers. Curl will normally always first attempt to use EPRT,
|
||||
then LPRT before using PORT, but with this option, it will use PORT right
|
||||
away. EPRT and LPRT are extensions to the original FTP protocol, and may not work
|
||||
on all servers, but they enable more functionality in a better way than the
|
||||
traditional PORT command.
|
||||
away. EPRT and LPRT are extensions to the original FTP protocol, and may not
|
||||
work on all servers, but they enable more functionality in a better way than
|
||||
the traditional PORT command.
|
||||
|
||||
\fB--eprt\fP can be used to explicitly enable EPRT again and \fB--no-eprt\fP
|
||||
is an alias for \fB--disable-eprt\fP.
|
||||
@ -397,9 +397,9 @@ operations. Use \fI--engine list\fP to print a list of build-time supported
|
||||
engines. Note that not all (or none) of the engines may be available at
|
||||
run-time.
|
||||
.IP "--environment"
|
||||
(RISC OS ONLY) Sets a range of environment variables, using the names the \fI-w\fP
|
||||
option supports, to allow easier extraction of useful information after having
|
||||
run curl.
|
||||
(RISC OS ONLY) Sets a range of environment variables, using the names the
|
||||
\fI-w\fP option supports, to allow easier extraction of useful information
|
||||
after having run curl.
|
||||
.IP "--egd-file <file>"
|
||||
(SSL) Specify the path name to the Entropy Gathering Daemon socket. The socket
|
||||
is used to seed the random engine for SSL connections. See also the
|
||||
@ -525,8 +525,9 @@ compliant than 'nocwd' but without the full penalty of 'multicwd'.
|
||||
behavior, but using this option can be used to override a previous
|
||||
\fI-P/-ftp-port\fP option. (Added in 7.11.0)
|
||||
|
||||
If this option is used several times, only the first one is used. Undoing an enforced passive really isn't doable but you must then
|
||||
instead enforce the correct \fI-P, --ftp-port\fP again.
|
||||
If this option is used several times, only the first one is used. Undoing an
|
||||
enforced passive really isn't doable but you must then instead enforce the
|
||||
correct \fI-P, --ftp-port\fP again.
|
||||
|
||||
Passive mode means that curl will try the EPSV command first and then PASV,
|
||||
unless \fI--disable-epsv\fP is used.
|
||||
@ -581,8 +582,9 @@ with a '?' separator.
|
||||
If used in combination with -I, the POST data will instead be appended to the
|
||||
URL with a HEAD request.
|
||||
|
||||
If this option is used several times, only the first one is used. This is because undoing a GET doesn't make sense, but you should
|
||||
then instead enforce the alternative method you prefer.
|
||||
If this option is used several times, only the first one is used. This is
|
||||
because undoing a GET doesn't make sense, but you should then instead enforce
|
||||
the alternative method you prefer.
|
||||
.IP "-H, --header <header>"
|
||||
(HTTP) Extra header to use when getting a web page. You may specify any number
|
||||
of extra headers. Note that if you should add a custom header that has the
|
||||
@ -591,9 +593,9 @@ header will be used instead of the internal one. This allows you to make even
|
||||
trickier stuff than curl would normally do. You should not replace internally
|
||||
set headers without knowing perfectly well what you're doing. Remove an
|
||||
internal header by giving a replacement without content on the right side of
|
||||
the colon, as in: -H \&"Host:". If you send the custom header with no-value then
|
||||
its header must be terminated with a semicolon, such as \-H "X-Custom-Header;"
|
||||
to send "X-Custom-Header:".
|
||||
the colon, as in: -H \&"Host:". If you send the custom header with no-value
|
||||
then its header must be terminated with a semicolon, such as \-H
|
||||
\&"X-Custom-Header;" to send "X-Custom-Header:".
|
||||
|
||||
curl will make sure that each header you add/replace is sent with the proper
|
||||
end-of-line marker, you should thus \fBnot\fP add that as a part of the header
|
||||
@ -604,8 +606,9 @@ See also the \fI-A, --user-agent\fP and \fI-e, --referer\fP options.
|
||||
|
||||
This option can be used multiple times to add/replace/remove multiple headers.
|
||||
.IP "--hostpubmd5 <md5>"
|
||||
(SCP/SFTP) Pass a string containing 32 hexadecimal digits. The string should be the 128 bit MD5 checksum of the remote host's public key, curl will refuse the
|
||||
connection with the host unless the md5sums match. (Added in 7.17.1)
|
||||
(SCP/SFTP) Pass a string containing 32 hexadecimal digits. The string should
|
||||
be the 128 bit MD5 checksum of the remote host's public key, curl will refuse
|
||||
the connection with the host unless the md5sums match. (Added in 7.17.1)
|
||||
.IP "--ignore-content-length"
|
||||
(HTTP)
|
||||
Ignore the Content-Length header. This is particularly useful for servers
|
||||
@ -633,8 +636,9 @@ make it discard all "session cookies". This will basically have the same effect
|
||||
as if a new session is started. Typical browsers always discard session
|
||||
cookies when they're closed down.
|
||||
.IP "-J, --remote-header-name"
|
||||
(HTTP) This option tells the \fI-O, --remote-name\fP option to use the server-specified
|
||||
Content-Disposition filename instead of extracting a filename from the URL.
|
||||
(HTTP) This option tells the \fI-O, --remote-name\fP option to use the
|
||||
server-specified Content-Disposition filename instead of extracting a filename
|
||||
from the URL.
|
||||
.IP "-k, --insecure"
|
||||
(SSL) This option explicitly allows curl to perform "insecure" SSL connections
|
||||
and transfers. All SSL connections are attempted to be made secure by using
|
||||
@ -811,9 +815,9 @@ Specify the maximum size (in bytes) of a file to download. If the file
|
||||
requested is larger than this value, the transfer will not start and curl will
|
||||
return with exit code 63.
|
||||
|
||||
\fBNOTE:\fP The file size is not always known prior to download, and for such files
|
||||
this option has no effect even if the file transfer ends up being larger than
|
||||
this given limit. This concerns both FTP and HTTP transfers.
|
||||
\fBNOTE:\fP The file size is not always known prior to download, and for such
|
||||
files this option has no effect even if the file transfer ends up being larger
|
||||
than this given limit. This concerns both FTP and HTTP transfers.
|
||||
.IP "--mail-rcpt <address>"
|
||||
(SMTP) Specify a single address that the given mail should get sent to. This
|
||||
option can be used multiple times to specify many recipients.
|
||||
@ -827,12 +831,12 @@ option to -1 to make it limitless.
|
||||
|
||||
If this option is used several times, the last one will be used.
|
||||
.IP "--metalink"
|
||||
This option can tell curl to parse and process a given URI as Metalink file (both
|
||||
version 3 and 4 (RFC 5854) are supported) and make use of the mirrors
|
||||
listed within for failover if there are errors (such as the file or
|
||||
server not being available). It will also verify the hash of the file
|
||||
after the download completes. The Metalink file itself is downloaded
|
||||
and processed in memory and not stored in the local file system.
|
||||
This option can tell curl to parse and process a given URI as Metalink file
|
||||
(both version 3 and 4 (RFC 5854) are supported) and make use of the mirrors
|
||||
listed within for failover if there are errors (such as the file or server not
|
||||
being available). It will also verify the hash of the file after the download
|
||||
completes. The Metalink file itself is downloaded and processed in memory and
|
||||
not stored in the local file system.
|
||||
|
||||
Example to use a remote Metalink file:
|
||||
|
||||
@ -1013,16 +1017,16 @@ available.
|
||||
|
||||
If this option is used several times, the last one will be used.
|
||||
.IP "--post301"
|
||||
(HTTP) Tells curl to respect RFC 2616/10.3.2 and not convert POST requests into GET
|
||||
requests when following a 301 redirection. The non-RFC behaviour is ubiquitous
|
||||
in web browsers, so curl does the conversion by default to maintain
|
||||
(HTTP) Tells curl to respect RFC 2616/10.3.2 and not convert POST requests
|
||||
into GET requests when following a 301 redirection. The non-RFC behaviour is
|
||||
ubiquitous in web browsers, so curl does the conversion by default to maintain
|
||||
consistency. However, a server may require a POST to remain a POST after such
|
||||
a redirection. This option is meaningful only when using \fI-L, --location\fP
|
||||
(Added in 7.17.1)
|
||||
.IP "--post302"
|
||||
(HTTP) Tells curl to respect RFC 2616/10.3.2 and not convert POST requests into GET
|
||||
requests when following a 302 redirection. The non-RFC behaviour is ubiquitous
|
||||
in web browsers, so curl does the conversion by default to maintain
|
||||
(HTTP) Tells curl to respect RFC 2616/10.3.2 and not convert POST requests
|
||||
into GET requests when following a 302 redirection. The non-RFC behaviour is
|
||||
ubiquitous in web browsers, so curl does the conversion by default to maintain
|
||||
consistency. However, a server may require a POST to remain a POST after such
|
||||
a redirection. This option is meaningful only when using \fI-L, --location\fP
|
||||
(Added in 7.19.1)
|
||||
@ -1111,24 +1115,24 @@ default config file search path.
|
||||
commands are sent BEFORE the transfer takes place (just after the initial PWD
|
||||
command in an FTP transfer, to be exact). To make commands take place after a
|
||||
successful transfer, prefix them with a dash '-'. To make commands be sent
|
||||
after libcurl has changed the working directory, just before the transfer
|
||||
after curl has changed the working directory, just before the transfer
|
||||
command(s), prefix the command with a '+' (this is only supported for
|
||||
FTP). You may specify any number of commands. If the server returns failure
|
||||
for one of the commands, the entire operation will be aborted. You must send
|
||||
syntactically correct FTP commands as RFC 959 defines to FTP servers, or one
|
||||
of the commands listed below to SFTP servers. This option can be used
|
||||
multiple times. When speaking to an FTP server, prefix the command with an
|
||||
asterisk (*) to make libcurl continue even if the command fails as by default
|
||||
asterisk (*) to make curl continue even if the command fails as by default
|
||||
curl will stop at first failure.
|
||||
|
||||
SFTP is a binary protocol. Unlike for FTP, libcurl interprets SFTP quote
|
||||
commands itself before sending them to the server. File names may be quoted
|
||||
SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP quote commands
|
||||
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 "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
|
||||
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"
|
||||
The chmod command modifies the file mode bits of the specified file. The
|
||||
@ -1186,9 +1190,10 @@ specifies two separate 100-byte ranges(*)(H)
|
||||
(*) = NOTE that this will cause the server to reply with a multipart
|
||||
response!
|
||||
|
||||
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 server's
|
||||
response will be unspecified, depending on the server's configuration.
|
||||
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 server's response will be unspecified, depending on the server's
|
||||
configuration.
|
||||
|
||||
You should also be aware that many HTTP/1.1 servers do not have this feature
|
||||
enabled, so that when you attempt to get a range, you'll instead get the whole
|
||||
@ -1200,7 +1205,7 @@ FTP command SIZE.
|
||||
|
||||
If this option is used several times, the last one will be used.
|
||||
.IP "-R, --remote-time"
|
||||
When used, this will make libcurl attempt to figure out the timestamp of the
|
||||
When used, this will make curl attempt to figure out the timestamp of the
|
||||
remote file, and if that is available make the local file get that same
|
||||
timestamp.
|
||||
.IP "--random-file <file>"
|
||||
@ -1409,7 +1414,7 @@ Set password for use with the TLS authentication method specified with
|
||||
7.21.4)
|
||||
.IP "--tr-encoding"
|
||||
(HTTP) Request a compressed Transfer-Encoding response using one of the
|
||||
algorithms libcurl supports, and uncompress the data while receiving it.
|
||||
algorithms curl supports, and uncompress the data while receiving it.
|
||||
|
||||
(Added in 7.21.6)
|
||||
.IP "--trace <file>"
|
||||
@ -1503,7 +1508,9 @@ to follow location: headers.
|
||||
.TP
|
||||
.B 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 \fI--remote-name\fP or \fI--output\fP option. It's most useful in combination with the \fI--remote-header-name\fP option. (Added in 7.25.1)
|
||||
is told to write to a file with the \fI--remote-name\fP or \fI--output\fP
|
||||
option. It's most useful in combination with the \fI--remote-header-name\fP
|
||||
option. (Added in 7.25.1)
|
||||
.TP
|
||||
.B http_code
|
||||
The numerical response code that was found in the last retrieved HTTP(S) or
|
||||
@ -1542,8 +1549,8 @@ started. time_redirect shows the complete execution time for multiple
|
||||
redirections. (Added in 7.12.3)
|
||||
.TP
|
||||
.B time_starttransfer
|
||||
The time, in seconds, it took from the start until the first byte was just about
|
||||
to be transferred. This includes time_pretransfer and also the time the
|
||||
The time, in seconds, it took from the start until the first byte was just
|
||||
about to be transferred. This includes time_pretransfer and also the time the
|
||||
server needed to calculate the result.
|
||||
.TP
|
||||
.B size_download
|
||||
@ -1580,7 +1587,7 @@ When an HTTP request was made without -L to follow redirects, this variable
|
||||
will show the actual URL a redirect \fIwould\fP take you to. (Added in 7.18.2)
|
||||
.TP
|
||||
.B ftp_entry_path
|
||||
The initial path libcurl ended up in when logging on to the remote FTP
|
||||
The initial path curl ended up in when logging on to the remote FTP
|
||||
server. (Added in 7.15.4)
|
||||
.TP
|
||||
.B ssl_verify_result
|
||||
@ -1603,8 +1610,8 @@ not be available. This is not the case if you can tunnel through the proxy, as
|
||||
one with the \fI-p, --proxytunnel\fP option.
|
||||
|
||||
User and password that might be provided in the proxy string are URL decoded
|
||||
by libcurl. This allows you to pass in special characters such as @ by using
|
||||
%40 or pass in a colon with %3a.
|
||||
by curl. This allows you to pass in special characters such as @ by using %40
|
||||
or pass in a colon with %3a.
|
||||
|
||||
The proxy host can be specified the exact same way as the proxy environment
|
||||
variables, including the protocol prefix (http://) and the embedded user +
|
||||
@ -1648,16 +1655,17 @@ this is a concern for you, try the \fI--connect-timeout\fP option.
|
||||
If this option is used several times, the last one will be used.
|
||||
.IP "-Y, --speed-limit <speed>"
|
||||
If a download is slower than this given speed (in bytes per second) for
|
||||
speed-time seconds it gets aborted. speed-time is set with \fI-y\fP and is 30 if
|
||||
not set.
|
||||
speed-time seconds it gets aborted. speed-time is set with \fI-y\fP and is 30
|
||||
if not set.
|
||||
|
||||
If this option is used several times, the last one will be used.
|
||||
.IP "-z/--time-cond <date expression>|<file>"
|
||||
(HTTP/FTP) 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 doesn't match any internal ones, it is
|
||||
taken as a filename and tries to get the modification date (mtime) from <file>
|
||||
instead. See the \fIcurl_getdate(3)\fP man pages for date expression details.
|
||||
date, or one that has been modified before that time. The <date expression>
|
||||
can be all sorts of date strings or if it doesn't match any internal ones, it
|
||||
is taken as a filename and tries to get the modification date (mtime) from
|
||||
<file> instead. See the \fIcurl_getdate(3)\fP 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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user