diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/curl.1 | 116 |
1 files changed, 25 insertions, 91 deletions
diff --git a/docs/curl.1 b/docs/curl.1 index 98bfc198c..5c0a5a084 100644 --- a/docs/curl.1 +++ b/docs/curl.1 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl 1 "5 Jan 2008" "Curl 7.18.0" "Curl Manual" +.TH curl 1 "5 June 2008" "Curl 7.18.3" "Curl Manual" .SH NAME curl \- transfer a URL .SH SYNOPSIS @@ -99,11 +99,15 @@ any response data to the terminal. If you prefer a progress "bar" instead of the regular meter, \fI-#\fP is your friend. .SH OPTIONS +In general, all boolean options are enabled with --option and yet again +disabled with --\fBno-\fPoption. That is, you use the exact same option name +but prefix it with "no-". However, in this list we mostly only list and show +the --option version of them. (This concept with --no options was added in +7.18.3. Previously most options were toggled on/off on repeated use of the +same command line option.) .IP "-a/--append" (FTP) When used in an FTP 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. - -If this option is used twice, the second one will disable append mode again. .IP "-A/--user-agent <agent string>" (HTTP) Specify the User-Agent string to send to the HTTP server. Some badly done CGIs fail if this field isn't set to "Mozilla/4.0". To encode blanks in @@ -124,9 +128,6 @@ Note that using --anyauth is not recommended if you do uploads from stdin, since it may require data to be sent twice and then the client must be able to rewind. If the need should arise when uploading from stdin, the upload operation will fail. - -If this option is used several times, the following occurrences make no -difference. .IP "-b/--cookie <name=data>" (HTTP) Pass the data to the HTTP server as a cookie. It is supposedly the @@ -152,16 +153,11 @@ used. Enable ASCII transfer when using FTP or LDAP. For FTP, this can also be enforced by using an URL that ends with ";type=A". This option causes data sent to stdout to be in text mode for win32 systems. - -If this option is used twice, the second one will disable ASCII usage. .IP "--basic" (HTTP) Tells curl to use HTTP Basic authentication. This is the default and 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 and \fI--negotiate\fP). - -If this option is used several times, the following occurrences make no -difference. .IP "--ciphers <list of ciphers>" (SSL) Specifies which ciphers to use in the connection. The list of ciphers must be using valid ciphers. Read up on SSL cipher list details on this URL: @@ -175,9 +171,7 @@ If this option is used several times, the last one will override the others. .IP "--compressed" (HTTP) Request a compressed response using one of the algorithms libcurl supports, and return the uncompressed document. If this option is used and -the server sends an unsupported encoding, Curl will report an error. - -If this option is used several times, each occurrence will toggle it on/off. +the server sends an unsupported encoding, curl will report an error. .IP "--connect-timeout <seconds>" Maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once curl has connected this option is @@ -220,9 +214,6 @@ To create remote directories when using FTP or SFTP, try \fI--ftp-create-dirs\fP. .IP "--crlf" (FTP) Convert LF to CRLF in upload. Useful for MVS (OS/390). - -If this option is used several times, the following occurrences make no -difference. .IP "-d/--data <data>" (HTTP) Sends the specified data in a POST request to the HTTP server, in the same way that a browser does when a user has filled in an HTML form and @@ -298,13 +289,15 @@ away. EPRT and LPRT are extensions to the original FTP protocol, may not work on all servers but enable more functionality in a better way than the traditional PORT command. -If this option is used several times, each occurrence will toggle this on/off. +Since curl 7.18.3, \fB--eprt\fP can be used to explicitly enable EPRT again +and \fB--no-eprt\fP is an alias for \fB--disable-eprt\fP. .IP "--disable-epsv" (FTP) Tell curl to disable the use of the EPSV command when doing passive FTP transfers. Curl will normally always first attempt to use EPSV before PASV, but with this option, it will not try using EPSV. -If this option is used several times, each occurrence will toggle this on/off. +Since curl 7.18.3, \fB--epsv\fP can be used to explicitly enable EPRT again +and \fB--no-epsv\fP is an alias for \fB--disable-epsv\fP. .IP "-D/--dump-header <file>" Write the protocol headers to the specified file. @@ -334,8 +327,6 @@ run-time. (RISC OS ONLY) Sets a range of environment variables, using the names the -w option supports, to easier allow extraction of useful information after having run curl. - -If this option is used several times, each occurrence will toggle this on/off. .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 @@ -400,8 +391,6 @@ will prevent curl from outputting that and return error 22. This method is not fail-safe and there are occasions where non-successful response codes will slip through, especially when authentication is involved (response codes 401 and 407). - -If this option is used twice, the second will again disable silent failure. .IP "--ftp-account [data]" (FTP) When an FTP server asks for "account data" after user name and password has been provided, this data is sent off using the ACCT command. (Added in @@ -413,8 +402,6 @@ If this option is used twice, the second will override the previous use. currently exist on the server, the standard behavior of curl is to fail. Using this option, curl will instead attempt to create missing directories. - -If this option is used twice, the second will again disable directory creation. .IP "--ftp-method [method]" (FTP) Control what method curl should use to reach a file on a FTP(S) server. The method argument should be one of the following alternatives: @@ -437,7 +424,8 @@ using this option can be used to override a previous --ftp-port option. (Added in 7.11.0) If this option is used several times, the following occurrences make no -difference. +difference. Undoing an enforced PASV really isn't doable but you must then +instead enforce the correct EPRT again. .IP "--ftp-alternative-to-user <command>" (FTP) If authenticating with the USER and PASS commands fails, send this command. When connecting to Tumbleweed's Secure Transport server over FTPS @@ -450,28 +438,19 @@ will re-use the same IP address it already uses for the control connection. (Added in 7.14.2) This option has no effect if PORT, EPRT or EPSV is used instead of PASV. - -If this option is used twice, the second will again use the server's suggested -address. .IP "--ftp-ssl" (FTP) Try to use SSL/TLS for the FTP connection. Reverts to a non-secure connection if the server doesn't support SSL/TLS. See also \fI--ftp-ssl-control\fP and \fI--ftp-ssl-reqd\fP for different levels of encryption required. (Added in 7.11.0) - -If this option is used twice, the second will again disable this. .IP "--ftp-ssl-control" (FTP) Require SSL/TLS for the ftp login, clear for transfer. Allows secure authentication, but non-encrypted data transfers for efficiency. Fails the transfer if the server doesn't support SSL/TLS. (Added in 7.16.0) - -If this option is used twice, the second will again disable this. .IP "--ftp-ssl-reqd" (FTP) Require SSL/TLS for the FTP connection. Terminates the connection if the server doesn't support SSL/TLS. (Added in 7.15.5) - -If this option is used twice, the second will again disable this. .IP "--ftp-ssl-ccc" (FTP) Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after authenticating. The rest of the @@ -479,8 +458,6 @@ control channel communication will be unencrypted. This allows NAT routers to follow the FTP transaction. The default mode is passive. See --ftp-ssl-ccc-mode for other modes. (Added in 7.16.1) - -If this option is used twice, the second will again disable this. .IP "--ftp-ssl-ccc-mode [active/passive]" (FTP) Use CCC (Clear Command Channel) Sets the CCC mode. The passive mode will not initiate the shutdown, but @@ -545,7 +522,8 @@ 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, the following occurrences make no -difference. +difference. This is because undoing a GET doesn't make sense, but you should +then instead enforce the alternative method you prefer. .IP "-h/--help" Usage help. .IP "-H/--header <header>" @@ -566,7 +544,7 @@ for you. 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" +.IP "--hostpubmd5 <md5>" 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. This option is only for SCP @@ -577,11 +555,8 @@ Ignore the Content-Length header. This is particularly useful for servers running Apache 1.x, which will report incorrect Content-Length for files larger than 2 gigabytes. .IP "-i/--include" -(HTTP) -Include the HTTP-header in the output. The HTTP-header includes things +(HTTP) Include the HTTP-header in the output. The HTTP-header includes things like server-name, date of the document, HTTP-version and more... - -If this option is used twice, the second will again disable header include. .IP "--interface <name>" Perform an operation using a specified interface. You can enter interface name, IP address or host name. An example could look like: @@ -595,15 +570,11 @@ Fetch the HTTP-header only! HTTP-servers feature the command HEAD which this uses to get nothing but the header of a document. When used on a FTP or FILE file, curl displays the file size and last modification time only. - -If this option is used twice, the second will again disable header only. .IP "-j/--junk-session-cookies" (HTTP) When curl is told to read cookies from a given file, this option will 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. - -If this option is used several times, each occurrence will toggle this on/off. .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 @@ -612,8 +583,6 @@ considered "insecure" to fail unless \fI-k/--insecure\fP is used. See this online resource for further details: \fBhttp://curl.haxx.se/docs/sslcerts.html\fP - -If this option is used twice, the second time will again disable it. .IP "--keepalive-time <seconds>" This option sets the time a connection needs to remain idle before sending keepalive probes and the time between individual keepalive probes. It is @@ -738,7 +707,6 @@ This option causes an FTP NLST command to be sent. Some FTP servers list only files in their response to NLST; they do not include subdirectories and symbolic links. -If this option is used twice, the second will again disable list only. .IP "--local-port <num>[-num]" Set a preferred number or range of local port numbers to use for the connection(s). Note that port numbers by nature is a scarce resource that @@ -759,8 +727,6 @@ When curl follows a redirect and the request is not a plain GET (for example POST or PUT), it will do the following request with a GET if the HTTP response was 301, 302, or 303. If the response code was any other 3xx code, curl will re-send the following request using the same unmodified method. - -If this option is used twice, the second will again disable location following. .IP "--location-trusted" (HTTP/HTTPS) Like \fI-L/--location\fP, but will allow sending the name + password to all hosts that the site may redirect to. This may or may not @@ -768,7 +734,6 @@ introduce a security breach if the site redirects you do a site to which you'll send your authentication info (which is plaintext in the case of HTTP Basic authentication). -If this option is used twice, the second will again disable location following. .IP "--max-filesize <bytes>" 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 @@ -802,8 +767,6 @@ to ftp to the machine host.domain.com with user name \&'myself' and password \&'secret' should look similar to: .B "machine host.domain.com login myself password secret" - -If this option is used twice, the second will again disable netrc usage. .IP "--netrc-optional" Very similar to \fI--netrc\fP, but this option makes the .netrc usage \fBoptional\fP and not mandatory as the \fI--netrc\fP does. @@ -833,12 +796,14 @@ will use a standard buffered output stream that will have the effect that it will output the data in chunks, not necessarily exactly when the data arrives. Using this option will disable that buffering. -If this option is used twice, the second will again switch on buffering. +Note that this is the negated option name documented. You can thus use +\fI--buffer\fP to enforce the buffering. .IP "--no-keepalive" Disables the use of keepalive messages on the TCP connection, as by default curl enables them. -If this option is used twice, the second will again enable keepalive. +Note that this is the negated option name documented. You can thus use +\fI--keepalive\fP to enforce keepalive. .IP "--no-sessionid" (SSL) Disable curl's use of SSL session-ID caching. By default all transfers are done using the cache. Note that while nothing ever should get hurt by @@ -846,8 +811,8 @@ attempting to reuse SSL session-IDs, there seem to be broken SSL implementations in the wild that may require you to disable this in order for you to succeed. (Added in 7.16.0) -If this option is used twice, the second will again switch on use of the -session cache. +Note that this is the negated option name documented. You can thus use +\fI--sessionid\fP to enforce session-ID caching. .IP "--ntlm" (HTTP) Enables NTLM authentication. The NTLM authentication method was designed by Microsoft and is used by IIS web servers. It is a proprietary @@ -903,41 +868,26 @@ a redirection. This option is meaningful only when using \fI-L/--location\fP Tells curl to pick a suitable authentication method when communicating with the given proxy. This might cause an extra request/response round-trip. (Added in 7.13.2) - -If this option is used twice, the second will again disable the proxy use-any -authentication. .IP "--proxy-basic" Tells curl to use HTTP Basic authentication when communicating with the given proxy. Use \fI--basic\fP for enabling HTTP Basic with a remote host. Basic is the default authentication method curl uses with proxies. - -If this option is used twice, the second will again disable proxy HTTP Basic -authentication. .IP "--proxy-digest" Tells curl to use HTTP Digest authentication when communicating with the given proxy. Use \fI--digest\fP for enabling HTTP Digest with a remote host. - -If this option is used twice, the second will again disable proxy HTTP Digest. .IP "--proxy-negotiate" Tells curl to use HTTP Negotiate authentication when communicating with the given proxy. Use \fI--negotiate\fP for enabling HTTP Negotiate -with a remote host. - -If this option is used twice, the second will again disable proxy HTTP -Negotiate. (Added in 7.17.1) +with a remote host. (Added in 7.17.1) .IP "--proxy-ntlm" Tells curl to use HTTP NTLM authentication when communicating with the given proxy. Use \fI--ntlm\fP for enabling NTLM with a remote host. - -If this option is used twice, the second will again disable proxy HTTP NTLM. .IP "-p/--proxytunnel" When an HTTP proxy is used (\fI-x/--proxy\fP), this option will cause non-HTTP protocols to attempt to tunnel through the proxy instead of merely using it to do HTTP-like operations. The tunnel approach is made with the HTTP proxy CONNECT request and requires that the proxy allows direct connect to the remote port number curl wants to tunnel through to. - -If this option is used twice, the second will again disable proxy tunnel. .IP "--pubkey <key>" (SSH) Public key file name. Allows you to provide your public key in this separate file. @@ -1033,14 +983,10 @@ If this option is used several times, the last one will be used. .IP "--raw" When used, it disables all internal HTTP decoding of content or transfer encodings and instead makes them passed on unaltered, raw. (Added in 7.16.2) - -If this option is used several times, each occurrence toggles this on/off. .IP "-R/--remote-time" When used, this will make libcurl attempt to figure out the timestamp of the remote file, and if that is available make the local file get that same timestamp. - -If this option is used twice, the second time disables this again. .IP "--retry <num>" If a transient error is returned when curl tries to perform a transfer, it will retry this number of times before giving up. Setting the number to 0 @@ -1075,12 +1021,8 @@ If this option is used multiple times, the last occurrence decide the amount. .IP "-s/--silent" Silent mode. Don't show progress meter or error messages. Makes Curl mute. - -If this option is used twice, the second will again disable silent mode. .IP "-S/--show-error" When used with -s it makes curl show error message if it fails. - -If this option is used twice, the second will again disable show error. .IP "--socks4 <host[:port]>" Use the specified SOCKS4 proxy. If the port number is not specified, it is assumed at port 1080. (Added in 7.15.2) @@ -1127,8 +1069,6 @@ If this option is used several times, the last one will be used. .IP "--tcp-nodelay" Turn on the TCP_NODELAY option. See the \fIcurl_easy_setopt(3)\fP man page for details about this option. (Added in 7.11.2) - -If this option is used several times, each occurrence toggles this on/off. .IP "-t/--telnet-option <OPT=val>" Pass options to the telnet protocol. Supported options are: @@ -1181,8 +1121,6 @@ If this option is used several times, the last one will be used. .IP "--trace-time" Prepends a time stamp to each trace or verbose line that curl displays. (Added in 7.14.0) - -If this option is used several times, each occurrence will toggle it on/off. .IP "-u/--user <user:password>" Specify user and password to use for server authentication. Overrides \fI-n/--netrc\fP and \fI--netrc-optional\fP. @@ -1222,8 +1160,6 @@ If you think this option still doesn't give you enough details, consider using \fI--trace\fP or \fI--trace-ascii\fP instead. This option overrides previous uses of \fI--trace-ascii\fP or \fI--trace\fP. - -If this option is used twice, the second will do nothing extra. .IP "-V/--version" Displays information about curl and the libcurl version it uses. @@ -1447,8 +1383,6 @@ IPv6 addresses only. .IP "-#/--progress-bar" Make curl display progress information as a progress bar instead of the default statistics. - -If this option is used twice, the second will again disable the progress bar. .SH FILES .I ~/.curlrc .RS |