~ubuntu-branches/ubuntu/gutsy/curl/gutsy

<p class="level0"><span Class="bold">curl</span> is a tool to transfer data from or to a server, using one of the supported protocols (HTTP, HTTPS, FTP, FTPS, TFTP, DICT, TELNET, LDAP or FILE). The command is designed to work without user interaction. 

<p class="level0">The URL syntax is protocol dependent. You'll find a detailed description in RFC 3986. 

<p class="level0">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. <a name="PROGRESS"></a><h2 class="nroffsh">PROGRESS METER</h2>

<p class="level0">curl normally displays a progress meter during operations, indicating amount of transfered data, transfer speeds and estimated time left etc. 

<p class="level0">However, since curl displays data to the terminal by default, if you invoke curl to do an operation and it is about to write data to the terminal, it <span Class="emphasis">disables</span> the progress meter as otherwise it would mess up the output mixing progress meter and response data. 

<p class="level0">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 (&gt;), -o [file] or similar. 

<p class="level0">It is not the same case for FTP upload as that operation is not spitting out any response data to the terminal. 

<p class="level0">If you prefer a progress "bar" instead of the regular meter, <a class="emphasis" href="#-">-#</a> is your friend. <a name="OPTIONS"></a><h2 class="nroffsh">OPTIONS</h2>

<p class="level1">(HTTP) Tells curl to figure out authentication method by itself, and use the most secure one the remote site claims it supports. This is done by first doing a request and checking the response-headers, thus inducing an extra network round-trip. This is used instead of setting a specific authentication method, which you can do with <a class="emphasis" href="#--basic">--basic</a>, <a class="emphasis" href="#--digest">--digest</a>, <a class="emphasis" href="#--ntlm">--ntlm</a>, and <a class="emphasis" href="#--negotiate">--negotiate</a>. 

<p class="level1">(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 <a class="emphasis" href="#--ntlm">--ntlm</a>, <a class="emphasis" href="#--digest">--digest</a> and <a class="emphasis" href="#--negotiate">--negotiate</a>). 

<p class="level1">If this option is used several times, the following occurrences make no difference. 

<p class="level1">(HTTP) Enables HTTP Digest authentication. This is a authentication that prevents the password from being sent over the wire in clear text. Use this in combination with the normal <a class="emphasis" href="#-u--user">-u/--user</a> option to set user name and password. See also <a class="emphasis" href="#--ntlm">--ntlm</a>, <a class="emphasis" href="#--negotiate">--negotiate</a> and <a class="emphasis" href="#--anyauth">--anyauth</a> for related options. 

<p class="level1">(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, may not work on all servers but enable more functionality in a better way than the traditional PORT command. 

<p class="level1">(HTTP) Sends the "Referer Page" information to the HTTP server. This can also be set with the <a class="emphasis" href="#-H--header">-H/--header</a> flag of course.  When used with <a class="emphasis" href="#-L--location">-L/--location</a> 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 don't set an initial --referer. 

<p class="level1">(HTTP) Fail silently (no output at all) on server errors. This is mostly done like this to better enable scripts etc to better deal with failed attempts. In normal cases when a HTTP server fails to deliver a document, it returns an HTML document stating so (which often also describes why and more). This flag will prevent curl from outputting that and return error 22. 

<p class="level1">(FTP) When an FTP URL/operation uses a path that doesn't currently exist on the server, the standard behavior of curl is to fail. Using this option, curl will instead attempt to create missing directories. 

<p class="level1">If this option is used twice, the second will again disable directory creation. 

<p class="level0"><a name="--ftp-method"></a><span class="nroffip">--ftp-method [method]</span> 

<p class="level1">(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: 

<p class="level2">

<p class="level1"><a name="multicwd"></a><span class="nroffip">multicwd</span> 

<p class="level2">curl does a single CWD operation for each path part in the given URL. For deep hierarchies this means very many commands. This is how RFC1738 says it should be done. This is the default but the slowest behavior. 

<p class="level1"><a name="nocwd"></a><span class="nroffip">nocwd</span> 

<p class="level2">curl does no CWD at all. curl will do SIZE, RETR, STOR etc and give a full path to the server for all these commands. This is the fastest behavior. 

<p class="level1"><a name="singlecwd"></a><span class="nroffip">singlecwd</span> 

<p class="level2">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'. 

<p class="level1">

<p class="level1">If this option is used several times, the following occurrences make no difference. 

<p class="level1">

<p class="level1">If this option is used twice, the second will again use the server's suggested address. 

<p class="level1">If this option is used several times, the following occurrences make no difference. 

<p class="level1">(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. 

<p class="level1">(SSL) This option explicitly allows curl to perform "insecure" SSL connections and transfers. All SSL connections are attempted to be made secure by using the CA certificate bundle installed by default. This makes all connections considered "insecure" to fail unless <a class="emphasis" href="#-k--insecure">-k/--insecure</a> is used. 

<p class="level1">Specify which config file to read curl arguments from. The config file is a text file in which command line arguments can be written which then will be used as if they were written on the actual command line. Options and their parameters must be specified on the same config file line. If the parameter is to contain white spaces, the parameter must be enclosed within quotes.  If the first column of a config line is a '#' character, the rest of the line will be treated as a comment. 

<p class="level0"><a name="--local-port"></a><span class="nroffip">--local-port &lt;num&gt;[-num]</span> 

<p class="level1">Set a prefered number or range of local port numbers to use for the connection(s).  Note that port numbers by nature is a scarce resource that will be busy at times so setting this range to something too narrow might cause unnecessary connection setup failures. (Added in 7.15.2) 

<p class="level1">(HTTP/HTTPS) If the server reports that the requested page has moved to a different location (indicated with a Location: header and a 3XX response code) this option will make curl redo the request on the new place. If used together with <a class="emphasis" href="#-i--include">-i/--include</a> or <a class="emphasis" href="#-I--head">-I/--head</a>, headers from all requested pages will be shown. When authentication is used, curl only sends its credentials to the initial host. If a redirect takes curl to a different host, it won't be able to intercept the user+password. See also <a class="emphasis" href="#--location-trusted">--location-trusted</a> on how to change this. You can limit the amount of redirects to follow by using the <a class="emphasis" href="#--max-redirs">--max-redirs</a> option. 

<p class="level1">(HTTP) Enables GSS-Negotiate authentication. The GSS-Negotiate method was designed by Microsoft and is used in their web applications. It is primarily meant as a support for Kerberos5 authentication but may be also used along with another authentication methods. For more information see IETF draft draft-brezak-spnego-http-04.txt. 

<p class="level1">(HTTP) Enables NTLM authentication. The NTLM authentication method was designed by Microsoft and is used by IIS web servers. It is a proprietary protocol, reversed engineered by clever people and implemented in curl based on their efforts. This kind of behavior should not be endorsed, you should encourage everyone who uses NTLM to switch to a public and documented authentication method instead. Such as Digest. 

<p class="level1">The remote file name to use for saving is extracted from the given URL, nothing else. 

<p class="level1">Tells curl to pick a suitable authentication method when communicating with the given proxy. This will cause an extra request/response round-trip. (Added in 7.13.2) 

<p class="level2">make curl pick the same IP address that is already used for the control connection 

<p class="level1">When curl is about to retry a transfer, it will first wait one second and then for all forthcoming retries it will double the waiting time until it reaches 10 minutes which then will be the delay between the rest of the retries.  By using <a class="emphasis" href="#--retry-delay">--retry-delay</a> you disable this exponential backoff algorithm. See also <a class="emphasis" href="#--retry-max-time">--retry-max-time</a> to limit the total time allowed for retries. (Added in 7.12.3) 

<p class="level1">Make curl sleep this amount of time between each retry when a transfer has failed with a transient error (it changes the default backoff time algorithm between retries). This option is only interesting if <a class="emphasis" href="#--retry">--retry</a> is also used. Setting this delay to zero will make curl use the default backoff time. (Added in 7.12.3) 

<p class="level1">The retry timer is reset before the first transfer attempt. Retries will be done as usual (see <a class="emphasis" href="#--retry">--retry</a>) as long as the timer hasn't reached this given limit. Notice that if the timer hasn't reached the limit, the request will be made and while performing, it may take longer than this given time period. To limit a single request&acute;s maximum time, use <a class="emphasis" href="#-m--max-time">-m/--max-time</a>. Set this option to zero to not timeout retries. (Added in 7.12.3) 

<p class="level1">If this option is used twice, the second will again disable silent mode. 

<p class="level0"><a name="--socks4"></a><span class="nroffip">--socks4 &lt;host[:port]&gt;</span> 

<p class="level1">Use the specified SOCKS4 proxy. If the port number is not specified, it is assumed at port 1080. (Added in 7.15.2) 

<p class="level0"><a name="--socks5"></a><span class="nroffip">--socks5 &lt;host[:port]&gt;</span> 

<p class="level1">Use the specified SOCKS5 proxy. If the port number is not specified, it is assumed at port 1080. (Added in 7.11.1) 

<p class="level1">This option overrides any previous use of <a class="emphasis" href="#-x--proxy">-x/--proxy</a>, as they are mutually exclusive. 

<p class="level1">If this option is used several times, the last one will be used. (This option was previously wrongly documented and used as --socks without the number appended.) 

<p class="level1">You can specify one -T for each URL on the command line. Each -T + URL pair specifies what to upload and to where. curl also supports "globbing" of the -T argument, meaning that you can upload multiple files to a single URL by using the same URL globbing style supported in the URL, like this: 

<p class="level1">If this option is used several times, the last one will be used. 

<p class="level1">If this option is used several times, the last one will be used. 

<p class="level1">Prepends a time stamp to each trace or verbose line that curl displays. (Added in 7.14.0) 

<p class="level1">If this option is used several times, each occurrence will toggle it on/off. 

<p class="level2"><span Class="bold">content_type</span> The Content-Type of the requested document, if there was any. 

<p class="level2"><span Class="bold">ftp_entry_path</span> The initial path libcurl ended up in when logging on to the remote FTP server. (Added in 7.15.4) 

<p class="level1">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. 

<p class="level1">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. 

<p class="level0"><a name="64"></a><span class="nroffip">64</span> 

<p class="level1">Requested FTP SSL level failed 

<p class="level0"><a name="65"></a><span class="nroffip">65</span> 

<p class="level1">Sending the data requires a rewind that failed 

<p class="level0"><a name="66"></a><span class="nroffip">66</span> 

<p class="level1">Failed to initialise SSL Engine 

<p class="level0"><a name="67"></a><span class="nroffip">67</span> 

<p class="level1">User, password or similar was not accepted and curl failed to login 

<p class="level0"><a name="68"></a><span class="nroffip">68</span> 

<p class="level1">File not found on TFTP server 

<p class="level0"><a name="69"></a><span class="nroffip">69</span> 

<p class="level1">Permission problem on TFTP server 

<p class="level0"><a name="70"></a><span class="nroffip">70</span> 

<p class="level1">Out of disk space on TFTP server 

<p class="level0"><a name="71"></a><span class="nroffip">71</span> 

<p class="level1">Illegal TFTP operation 

<p class="level0"><a name="72"></a><span class="nroffip">72</span> 

<p class="level1">Unknown TFTP transfer ID 

<p class="level0"><a name="73"></a><span class="nroffip">73</span> 

<p class="level1">File already exists (TFTP) 

<p class="level0"><a name="74"></a><span class="nroffip">74</span> 

<p class="level1">No such user (TFTP) 

<p class="level0"><a name="75"></a><span class="nroffip">75</span> 

<p class="level1">Character conversion failed 

<p class="level0"><a name="76"></a><span class="nroffip">76</span> 

<p class="level1">Character conversion functions required