diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/curl.1 | 170 |
1 files changed, 89 insertions, 81 deletions
diff --git a/docs/curl.1 b/docs/curl.1 index ee7d71b9f..5f66c7f47 100644 --- a/docs/curl.1 +++ b/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 |