~ubuntu-branches/ubuntu/natty/curl/natty-proposed

curl is a tool to transfer data from or to a server, using one of the supported protocols (HTTP, HTTPS, FTP, FTPS, SCP, SFTP, TFTP, DICT, TELNET, LDAP or FILE). The command is designed to work without user interaction.

curl offers a busload of useful tricks like proxy support, user authentication, ftp upload, HTTP post, SSL connections, cookies, file transfer resume and more. As you will see below, the number of features will make your head spin!

curl offers a busload of useful tricks like proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer resume and more. As you will see below, the number of features will make your head spin!

curl is powered by libcurl for all transfer-related features. See libcurl (3) for details. <a name="URL"></a><h2 class="nroffsh">URL</h2>

The URL syntax is protocol dependent. You'll find a detailed description in RFC 3986.

The URL syntax is protocol-dependent. You'll find a detailed description in RFC 3986.

You can specify multiple URLs or parts of URLs by writing part sets within braces as in:

<a href="http://site">http://site</a>.{one,two,three}.com

or you can get sequences of alphanumeric series by using [] as in:

No nesting of the sequences is supported at the moment, but you can use several ones next to each other:

<a href="http://any.org/archive">http://any.org/archive</a>[1996-1999]/vol[1-4]/part{a,b,c}.html

You can specify any amount of URLs on the command line. They will be fetched in a sequential manner in the specified order.

Since curl 7.15.1 you can also specify step counter for the ranges, so that you can get every Nth number or letter:

Since curl 7.15.1 you can also specify a step counter for the ranges, so that you can get every Nth number or letter:

<a href="http://www.numericals.com/file">http://www.numericals.com/file</a>[1-100:10].txt  <a href="http://www.letters.com/file">http://www.letters.com/file</a>[a-z:2].txt

If you specify URL without protocol:// prefix, curl will attempt to guess what protocol you might want. It will then default to HTTP but try other protocols based on often-used host name prefixes. For example, for host names starting with "ftp." curl will assume you want to speak FTP.

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>

curl normally displays a progress meter during operations, indicating amount of transferred data, transfer speeds and estimated time left etc.

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 disables the progress meter as otherwise it would mess up the output mixing progress meter and response data.

curl normally displays a progress meter during operations, indicating the amount of transferred data, transfer speeds and estimated time left, etc.

However, since curl displays this 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 disables the progress meter as otherwise it would mess up the output mixing progress 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 (>), -o [file] or similar.

It is not the same case for FTP upload as that operation is not spitting out any response data to the terminal.

It is not the same case for 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, <a class="emphasis" href="#-">-#</a> is your friend. <a name="OPTIONS"></a><h2 class="nroffsh">OPTIONS</h2>

In general, all boolean options are enabled with --option and yet again disabled with --no-option. 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.19.0. Previously most options were toggled on/off on repeated use of the same command line option.)

<a name="-a--append"></a>-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.

(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. Note that this flag is ignored by some SSH servers (including OpenSSH).

<a name="-A--user-agent"></a>-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 the string, surround the string with single quote marks. This can also be set with the <a class="emphasis" href="#-H--header">-H/--header</a> option of course.

If this option is set more than once, the last one will be the one that's used.

<a name="--anyauth"></a>--anyauth

(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 possibly 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>.

(HTTP) Tells curl to figure out authentication method by itself, and use the most secure one the remote site claims to support. This is done by first doing a request and checking the response-headers, thus possibly 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>.

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.

<a name="-b--cookie"></a>-b/--cookie <name=data>

(HTTP) Pass the data to the HTTP server as a cookie. It is supposedly the data previously received from the server in a "Set-Cookie:" line. The data should be in the format "NAME1=VALUE1; NAME2=VALUE2".

If no '=' letter is used in the line, it is treated as a filename to use to read previously stored cookie lines from, which should be used in this session if they match. Using this method also activates the "cookie parser" which will make curl record incoming cookies too, which may be handy if you're using this in combination with the <a class="emphasis" href="#-L--location">-L/--location</a> option. The file format of the file to read cookies from should be plain HTTP headers or the Netscape/Mozilla cookie file format.

If no '=' symbol is used in the line, it is treated as a filename to use to read previously stored cookie lines from, which should be used in this session if they match. Using this method also activates the "cookie parser" which will make curl record incoming cookies too, which may be handy if you're using this in combination with the <a class="emphasis" href="#-L--location">-L/--location</a> option. The file format of the file to read cookies from should be plain HTTP headers or the Netscape/Mozilla cookie file format.

NOTE that the file specified with <a class="emphasis" href="#-b--cookie">-b/--cookie</a> is only used as input. No cookies will be stored in the file. To store cookies, use the <a class="emphasis" href="#-c--cookie-jar">-c/--cookie-jar</a> option or you could even save the HTTP headers to a file using <a class="emphasis" href="#-D--dump-header">-D/--dump-header</a>!

If this option is set more than once, the last one will be the one that's used.

<a name="-B--use-ascii"></a>-B/--use-ascii

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.

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

If this option is used several times, the following occurrences make no difference.

(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>, or <a class="emphasis" href="#--negotiate">--negotiate</a>).

<a name="--ciphers"></a>--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: <a href="http://www.openssl.org/docs/apps/ciphers.html">http://www.openssl.org/docs/apps/ciphers.html</a>

(SSL) Specifies which ciphers to use in the connection. The list of ciphers must specify valid ciphers. Read up on SSL cipher list details on this URL: <a href="http://www.openssl.org/docs/apps/ciphers.html">http://www.openssl.org/docs/apps/ciphers.html</a>

NSS ciphers are done differently than OpenSSL and GnuTLS. The full list of NSS ciphers is in the NSSCipherSuite entry at this URL: <a href="http://directory.fedora.redhat.com/docs/mod_nss.html">http://directory.fedora.redhat.com/docs/mod_nss.html</a>#Directives

If this option is used several times, the last one will override the others.

<a name="--compressed"></a>--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.

<a name="--connect-timeout"></a>--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 of no more use. See also the <a class="emphasis" href="#-m--max-time">-m/--max-time</a> option.

100

If this option is used several times, the last one will be used.

103

NOTE If the cookie jar can't be created or written to, the whole curl operation won't fail or even report an error clearly. Using -v will get a warning displayed, but that is the only visible feedback you get about this possibly lethal situation.

104

If this option is used several times, the last specified file name will be used.

105

100

<a name="-C--continue-at"></a>-C/--continue-at <offset>

106

Continue/Resume a previous file transfer at the given offset. The given offset is the exact number of bytes that will be skipped counted from the beginning of the source file before it is transferred to the destination. If used with uploads, the ftp server command SIZE will not be used by curl.

101

Continue/Resume a previous file transfer at the given offset. The given offset is the exact number of bytes that will be skipped, counting from the beginning of the source file before it is transferred to the destination. If used with uploads, the FTP server command SIZE will not be used by curl.

107

102

Use "-C -" to tell curl to automatically find out where/how to resume the transfer. It then uses the given output/input files to figure that out.

108

103

If this option is used several times, the last one will be used.

109

104

<a name="--create-dirs"></a>--create-dirs

111

106

To create remote directories when using FTP or SFTP, try <a class="emphasis" href="#--ftp-create-dirs">--ftp-create-dirs</a>.

112

107

<a name="--crlf"></a>--crlf

113

108

(FTP) Convert LF to CRLF in upload. Useful for MVS (OS/390).

114

If this option is used several times, the following occurrences make no difference.

115

109

116

110

(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 presses the submit button. This will cause curl to pass the data to the server using the content-type application/x-www-form-urlencoded. Compare to <a class="emphasis" href="#-F--form">-F/--form</a>.

117

<a class="emphasis" href="#-d--data">-d/--data</a> is the same as --data-ascii. To post data purely binary, you should instead use the <a class="emphasis" href="#--data-binary">--data-binary</a> option. To URL encode the value of a form field you may use <a class="emphasis" href="#--data-urlencode">--data-urlencode</a>.

118

If any of these options is used more than once on the same command line, the data pieces specified will be merged together with a separating &-letter. Thus, using '-d name=daniel -d skill=lousy' would generate a post chunk that looks like 'name=daniel&skill=lousy'.

119

If you start the data with the letter @, the rest should be a file name to read the data from, or - if you want curl to read the data from stdin. The contents of the file must already be url-encoded. Multiple files can also be specified. Posting data from a file named 'foobar' would thus be done with --data @foobar.

111

<a class="emphasis" href="#-d--data">-d/--data</a> is the same as --data-ascii. To post data purely binary, you should instead use the <a class="emphasis" href="#--data-binary">--data-binary</a> option. To URL-encode the value of a form field you may use <a class="emphasis" href="#--data-urlencode">--data-urlencode</a>.

112

If any of these options is used more than once on the same command line, the data pieces specified will be merged together with a separating &-symbol. Thus, using '-d name=daniel -d skill=lousy' would generate a post chunk that looks like 'name=daniel&skill=lousy'.

113

If you start the data with the letter @, the rest should be a file name to read the data from, or - if you want curl to read the data from stdin. The contents of the file must already be URL-encoded. Multiple files can also be specified. Posting data from a file named 'foobar' would thus be done with --data @foobar.

120

114

<a name="--data-binary"></a>--data-binary <data>

121

115

(HTTP) This posts data exactly as specified with no extra processing whatsoever.

122

116

If you start the data with the letter @, the rest should be a filename. Data is posted in a similar manner as --data-ascii does, except that newlines are preserved and conversions are never done.

123

If this option is used several times, the ones following the first will append data. As described in <a class="emphasis" href="#-d--data">-d/--data</a>.

117

If this option is used several times, the ones following the first will append data as described in <a class="emphasis" href="#-d--data">-d/--data</a>.

124

118

<a name="--data-urlencode"></a>--data-urlencode <data>

125

(HTTP) This posts data, similar to the other --data options with the exception that this performs URL encoding. (Added in 7.18.0)

126

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:

119

(HTTP) This posts data, similar to the other --data options with the exception that this performs URL-encoding. (Added in 7.18.0)

120

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:

127

121

128

122

<a name="content"></a>content

129

This will make curl URL encode the content and pass that on. Just be careful so that the content doesn't contain any = or @ letters, as that will then make the syntax match one of the other cases below!

123

This will make curl URL-encode the content and pass that on. Just be careful so that the content doesn't contain any = or @ symbols, as that will then make the syntax match one of the other cases below!

130

124

<a name="content"></a>=content

131

This will make curl URL encode the content and pass that on. The preceding = letter is not included in the data.

125

This will make curl URL-encode the content and pass that on. The preceding = symbol is not included in the data.

132

126

<a name="namecontent"></a>name=content

133

This will make curl URL encode the content part and pass that on. Note that the name part is expected to be URL encoded already.

127

This will make curl URL-encode the content part and pass that on. Note that the name part is expected to be URL-encoded already.

134

128

<a name="filename"></a>@filename

135

This will make curl load data from the given file (including any newlines), URL encode that data and pass it on in the POST.

129

This will make curl load data from the given file (including any newlines), URL-encode that data and pass it on in the POST.

136

130

<a name="namefilename"></a>name@filename

137

This will make curl load data from the given file (including any newlines), URL encode that data and pass it on in the POST. The name part gets an equal sign appended, resulting in name=urlencoded-file-content. Note that the name is expected to be URL encoded already.

131

This will make curl load data from the given file (including any newlines), URL-encode that data and pass it on in the POST. The name part gets an equal sign appended, resulting in name=urlencoded-file-content. Note that the name is expected to be URL-encoded already.

138

132

139

133

<a name="--digest"></a>--digest

140

134

(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.

141

135

If this option is used several times, the following occurrences make no difference.

142

136

<a name="--disable-eprt"></a>--disable-eprt

143

(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.

144

If this option is used several times, each occurrence will toggle this on/off.

137

(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.

138

Since curl 7.19.0, --eprt can be used to explicitly enable EPRT again and --no-eprt is an alias for <a class="bold" href="#--disable-eprt">--disable-eprt</a>.

139

Disabling EPRT only changes the active behavior. If you want to switch to passive mode you need to not use <a class="emphasis" href="#-P--ftp-port">-P/--ftp-port</a> or force it with <a class="emphasis" href="#--ftp-pasv">--ftp-pasv</a>.

145

140

<a name="--disable-epsv"></a>--disable-epsv

146

141

(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.

147

If this option is used several times, each occurrence will toggle this on/off.

142

Since curl 7.19.0, --epsv can be used to explicitly enable EPRT again and --no-epsv is an alias for <a class="bold" href="#--disable-epsv">--disable-epsv</a>.

143

Disabling EPSV only changes the passive behavior. If you want to switch to active mode you need to use <a class="emphasis" href="#-P--ftp-port">-P/--ftp-port</a>.

148

144

<a name="-D--dump-header"></a>-D/--dump-header <file>

149

145

Write the protocol headers to the specified file.

150

This option is handy to use when you want to store the headers that a HTTP site sends to you. Cookies from the headers could then be read in a second curl invoke by using the <a class="emphasis" href="#-b--cookie">-b/--cookie</a> option! The <a class="emphasis" href="#-c--cookie-jar">-c/--cookie-jar</a> option is however a better way to store cookies.

151

When used on FTP, the ftp server response lines are considered being "headers" and thus are saved there.

146

This option is handy to use when you want to store the headers that a HTTP site sends to you. Cookies from the headers could then be read in a second curl invocation by using the <a class="emphasis" href="#-b--cookie">-b/--cookie</a> option! The <a class="emphasis" href="#-c--cookie-jar">-c/--cookie-jar</a> option is however a better way to store cookies.

147

When used in FTP, the FTP server response lines are considered being "headers" and thus are saved there.

152

148

If this option is used several times, the last one will be used.

153

149

<a name="-e--referer"></a>-e/--referer <URL>

154

150

(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.

156

152

<a name="--engine"></a>--engine <name>

157

153

Select the OpenSSL crypto engine to use for cipher operations. Use <a class="emphasis" href="#--engine">--engine list</a> to print a list of build-time supported engines. Note that not all (or none) of the engines may be available at run-time.

158

154

<a name="--environment"></a>--environment

159

(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.

160

If this option is used several times, each occurrence will toggle this on/off.

155

(RISC OS ONLY) Sets a range of environment variables, using the names the -w option supports, to allow easier extraction of useful information after having run curl.

161

156

162

157

(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 <a class="emphasis" href="#--random-file">--random-file</a> option.

163

158

169

164

If this option is used several times, the last one will be used.

170

165

<a name="--cacert"></a>--cacert <CA certificate>

171

166

(SSL) Tells curl to use the specified certificate file to verify the peer. The file may contain multiple CA certificates. The certificate(s) must be in PEM format. Normally curl is built to use a default file for this, so this option is typically used to alter that default file.

172

curl recognizes the environment variable named 'CURL_CA_BUNDLE' if that is set, and uses the given path as a path to a CA cert bundle. This option overrides that variable.

167

curl recognizes the environment variable named 'CURL_CA_BUNDLE' if it is set, and uses the given path as a path to a CA cert bundle. This option overrides that variable.

173

168

The windows version of curl will automatically look for a CA certs file named ´curl-ca-bundle.crt´, either in the same directory as curl.exe, or in the Current Working Directory, or in any folder along your PATH.

174

169

If curl is built against the NSS SSL library then this option tells curl the nickname of the CA certificate to use within the NSS database defined by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be loaded.

175

170

If this option is used several times, the last one will be used.

177

172

(SSL) Tells curl to use the specified certificate directory to verify the peer. The certificates must be in PEM format, and the directory must have been processed using the c_rehash utility supplied with openssl. Using <a class="emphasis" href="#--capath">--capath</a> can allow curl to make SSL-connections much more efficiently than using <a class="emphasis" href="#--cacert">--cacert</a> if the <a class="emphasis" href="#--cacert">--cacert</a> file contains many CA certificates.

178

173

If this option is used several times, the last one will be used.

179

174

<a name="-f--fail"></a>-f/--fail

180

(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.

175

(HTTP) Fail silently (no output at all) on server errors. This is mostly done 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.

181

176

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).

182

If this option is used twice, the second will again disable silent failure.

183

177

<a name="--ftp-account"></a>--ftp-account [data]

184

178

(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 7.13.0)

185

179

If this option is used twice, the second will override the previous use.

186

180

<a name="--ftp-create-dirs"></a>--ftp-create-dirs

187

181

(FTP/SFTP) When an FTP or SFTP 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.

188

If this option is used twice, the second will again disable directory creation.

189

182

<a name="--ftp-method"></a>--ftp-method [method]

190

183

(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:

191

184

195

188

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.

196

189

<a name="singlecwd"></a>singlecwd

197

190

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'.

198

191

(Added in 7.15.1)

199

192

<a name="--ftp-pasv"></a>--ftp-pasv

200

(FTP) Use PASV when transferring. PASV is the internal default behavior, but using this option can be used to override a previous --ftp-port option. (Added in 7.11.0)

201

If this option is used several times, the following occurrences make no difference.

193

(FTP) Use passive mode for the data conection. Passive is the internal default behavior, but using this option can be used to override a previous -P/-ftp-port option. (Added in 7.11.0)

194

If this option is used several times, the following occurrences make no difference. Undoing an enforced passive really isn't doable but you must then instead enforce the correct <a class="emphasis" href="#-P--ftp-port">-P/--ftp-port</a> again.

195

Passive mode means that curl will try the EPSV command first and then PASV, unless <a class="emphasis" href="#--disable-epsv">--disable-epsv</a> is used.

202

196

<a name="--ftp-alternative-to-user"></a>--ftp-alternative-to-user <command>

203

197

(FTP) If authenticating with the USER and PASS commands fails, send this command. When connecting to Tumbleweed's Secure Transport server over FTPS using a client certificate, using "SITE AUTH" will tell the server to retrieve the username from the certificate. (Added in 7.15.5)

204

198

<a name="--ftp-skip-pasv-ip"></a>--ftp-skip-pasv-ip

205

199

(FTP) Tell curl to not use the IP address the server suggests in its response to curl's PASV command when curl connects the data connection. Instead curl will re-use the same IP address it already uses for the control connection. (Added in 7.14.2)

206

200

This option has no effect if PORT, EPRT or EPSV is used instead of PASV.

207

If this option is used twice, the second will again use the server's suggested address.

208

201

<a name="--ftp-ssl"></a>--ftp-ssl

209

202

(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 <a class="emphasis" href="#--ftp-ssl-control">--ftp-ssl-control</a> and <a class="emphasis" href="#--ftp-ssl-reqd">--ftp-ssl-reqd</a> for different levels of encryption required. (Added in 7.11.0)

210

If this option is used twice, the second will again disable this.

211

203

<a name="--ftp-ssl-control"></a>--ftp-ssl-control

212

(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)

213

If this option is used twice, the second will again disable this.

204

(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)

214

205

<a name="--ftp-ssl-reqd"></a>--ftp-ssl-reqd

215

206

(FTP) Require SSL/TLS for the FTP connection. Terminates the connection if the server doesn't support SSL/TLS. (Added in 7.15.5)

216

If this option is used twice, the second will again disable this.

217

207

<a name="--ftp-ssl-ccc"></a>--ftp-ssl-ccc

218

208

(FTP) Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after authenticating. The rest of the 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)

219

If this option is used twice, the second will again disable this.

220

209

<a name="--ftp-ssl-ccc-mode"></a>--ftp-ssl-ccc-mode [active/passive]

221

210

(FTP) Use CCC (Clear Command Channel) Sets the CCC mode. The passive mode will not initiate the shutdown, but instead wait for the server to do it, and will not reply to the shutdown from the server. The active mode initiates the shutdown and waits for a reply from the server. (Added in 7.16.2)

222

211

223

(HTTP) This lets curl emulate a filled in form in which a user has pressed the submit button. This causes curl to POST data using the Content-Type multipart/form-data according to RFC1867. 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 letter <. 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.

212

(HTTP) This lets curl emulate a filled-in form in which a user has pressed the submit button. This causes curl to POST data using the Content-Type multipart/form-data according to RFC1867. 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 file.

224

213

Example, to send your password file to the server, where 'password' is the name of the form-field to which /etc/passwd will be the input:

225

214

curl -F password=@/etc/passwd www.mypasswords.com

226

215

To read the file's content from stdin instead of a file, use - where the file name should've been. This goes for both @ and < constructs.

237

226

<a name="-g--globoff"></a>-g/--globoff

238

227

This option switches off the "URL globbing parser". When you set this option, you can specify URLs that contain the letters {}[] without having them being interpreted by curl itself. Note that these letters are not normal legal URL contents but they should be encoded according to the URI standard.

239

228

<a name="-G--get"></a>-G/--get

240

When used, this option will make all data specified with <a class="emphasis" href="#-d--data">-d/--data</a> or <a class="emphasis" href="#--data-binary">--data-binary</a> to be used in a HTTP GET request instead of the POST request that otherwise would be used. The data will be appended to the URL with a '?' separator.

229

241

230

If used in combination with -I, the POST data will instead be appended to the URL with a HEAD request.

242

If this option is used several times, the following occurrences make no difference.

231

If this option is used several times, the following occurrences make no difference. This is because undoing a GET doesn't make sense, but you should then instead enforce the alternative method you prefer.

243

232

<a name="-h--help"></a>-h/--help

244

233

Usage help.

245

234

<a name="-H--header"></a>-H/--header <header>

246

235

(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 same name as one of the internal ones curl would use, your externally set 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:".

247

curl will make sure that each header you add/replace get sent with the proper end of line marker, you should thus not add that as a part of the header content: do not add newlines or carriage returns they will only mess things up for you.

236

curl will make sure that each header you add/replace is sent with the proper end-of-line marker, you should thus not add that as a part of the header content: do not add newlines or carriage returns, they will only mess things up for you.

248

237

See also the <a class="emphasis" href="#-A--user-agent">-A/--user-agent</a> and <a class="emphasis" href="#-e--referer">-e/--referer</a> options.

249

238

This option can be used multiple times to add/replace/remove multiple headers.

250

<a name="--hostpubmd5"></a>--hostpubmd5

239

<a name="--hostpubmd5"></a>--hostpubmd5 <md5>

251

240

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 and SFTP transfers. (Added in 7.17.1)

252

241

<a name="--ignore-content-length"></a>--ignore-content-length

253

242

(HTTP) 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.

254

243

<a name="-i--include"></a>-i/--include

255

244

(HTTP) Include the HTTP-header in the output. The HTTP-header includes things like server-name, date of the document, HTTP-version and more...

256

If this option is used twice, the second will again disable header include.

257

245

<a name="--interface"></a>--interface <name>

258

246

Perform an operation using a specified interface. You can enter interface name, IP address or host name. An example could look like:

259

247

curl --interface eth0:1 <a href="http://www.netscape.com/">http://www.netscape.com/</a>

260

248

If this option is used several times, the last one will be used.

261

249

<a name="-I--head"></a>-I/--head

262

250

(HTTP/FTP/FILE) 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.

263

If this option is used twice, the second will again disable header only.

264

251

<a name="-j--junk-session-cookies"></a>-j/--junk-session-cookies

265

252

(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.

266

If this option is used several times, each occurrence will toggle this on/off.

267

253

<a name="-k--insecure"></a>-k/--insecure

268

(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.

254

(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" fail unless <a class="emphasis" href="#-k--insecure">-k/--insecure</a> is used.

269

255

See this online resource for further details: <a href="http://curl.haxx.se/docs/sslcerts.html">http://curl.haxx.se/docs/sslcerts.html</a>

270

If this option is used twice, the second time will again disable it.

271

256

<a name="--keepalive-time"></a>--keepalive-time <seconds>

272

257

This option sets the time a connection needs to remain idle before sending keepalive probes and the time between individual keepalive probes. It is currently effective on operating systems offering the TCP_KEEPIDLE and TCP_KEEPINTVL socket options (meaning Linux, recent AIX, HP-UX and more). This option has no effect if <a class="emphasis" href="#--no-keepalive">--no-keepalive</a> is used. (Added in 7.18.0)

273

258

If this option is used multiple times, the last occurrence sets the amount.

275

260

(SSL/SSH) Private key file name. Allows you to provide your private key in this separate file.

276

261

If this option is used several times, the last one will be used.

277

262

278

(SSL) Private key file type. Specify which type your <a class="emphasis" href="#--key">--key</a> provided private key is. DER, PEM and ENG are supported. If not specified, PEM is assumed.

263

(SSL) Private key file type. Specify which type your <a class="emphasis" href="#--key">--key</a> provided private key is. DER, PEM, and ENG are supported. If not specified, PEM is assumed.

279

264

If this option is used several times, the last one will be used.

280

265

281

(FTP) Enable Kerberos authentication and use. The level must be entered and should be one of 'clear', 'safe', 'confidential' or 'private'. Should you use a level that is not one of these, 'private' will instead be used.

282

This option requires that the library was built with kerberos4 or GSSAPI (GSS-Negotiate) support. This is not very common. Use <a class="emphasis" href="#-V--version">-V/--version</a> to see if your curl supports it.

266

(FTP) Enable Kerberos authentication and use. The level must be entered and should be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a level that is not one of these, 'private' will instead be used.

267

This option requires a library built with kerberos4 or GSSAPI (GSS-Negotiate) support. This is not very common. Use <a class="emphasis" href="#-V--version">-V/--version</a> to see if your curl supports it.

283

268

If this option is used several times, the last one will be used.

284

269

<a name="-K--config"></a>-K/--config <config file>

285

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, separated by white space, colon, the equals sign or any combination thereof (however, the preferred separator is the equals sign). If the parameter is to contain white spaces, the parameter must be enclosed within quotes. Within double quotes, the following escape sequences are available: \\, \", \t, \n, \r and \v. A backlash preceding any other letter is ignored. If the first column of a config line is a '#' character, the rest of the line will be treated as a comment. Only write one option per physical line in the config file.

270

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, separated by whitespace, colon, the equals sign or any combination thereof (however, the preferred separator is the equals sign). If the parameter is to contain whitespace, the parameter must be enclosed within quotes. Within double quotes, the following escape sequences are available: \\, \", \t, \n, \r and \v. A backslash preceding any other letter is ignored. If the first column of a config line is a '#' character, the rest of the line will be treated as a comment. Only write one option per physical line in the config file.

286

271

Specify the filename to -K/--config as '-' to make curl read the file from stdin.

287

272

Note that to be able to specify a URL in the config file, you need to specify it using the <a class="emphasis" href="#--url">--url</a> option, and not by simply writing the URL on its own line. So, it could look similar to this:

288

273

url = "<a href="http://curl.haxx.se/docs/">http://curl.haxx.se/docs/</a>"

289

274

Long option names can optionally be given in the config file without the initial double dashes.

290

275

When curl is invoked, it always (unless <a class="emphasis" href="#-q">-q</a> is used) checks for a default config file and uses it if found. The default config file is checked for in the following places in this order:

291

1) curl tries to find the "home dir": It first checks for the CURL_HOME and then the HOME environment variables. Failing that, it uses getpwuid() on unix-like systems (which returns the home dir given the current user in your system). On Windows, it then checks for the APPDATA variable, or as a last resort the '%USERPROFILE%Application Data'.

292

2) On windows, if there is no _curlrc file in the home dir, it checks for one in the same dir the executable curl is placed. On unix-like systems, it will simply try to load .curlrc from the determined home dir.

276

1) curl tries to find the "home dir": It first checks for the CURL_HOME and then the HOME environment variables. Failing that, it uses getpwuid() on UNIX-like systems (which returns the home dir given the current user in your system). On Windows, it then checks for the APPDATA variable, or as a last resort the '%USERPROFILE%\Application Data'.

277

2) On windows, if there is no _curlrc file in the home dir, it checks for one in the same dir the curl executable is placed. On UNIX-like systems, it will simply try to load .curlrc from the determined home dir.

293

278

<pre>

294

279

# --- Example file ---

295

280

# this is a comment

306

291

307

292

This option can be used multiple times to load multiple config files.

308

293

<a name="--libcurl"></a>--libcurl <file>

309

Append this option to any ordinary curl command line, and you will get a libcurl-using source code written to the file that does the equivalent operation of what your command line operation does!

294

Append this option to any ordinary curl command line, and you will get a libcurl-using source code written to the file that does the equivalent of what your command-line operation does!

310

295

NOTE: this does not properly support -F and the sending of multipart formposts, so in those cases the output program will be missing necessary calls to curl_formadd(3), and possibly more.

311

296

If this option is used several times, the last given file name will be used. (Added in 7.16.1)

312

297

<a name="--limit-rate"></a>--limit-rate <speed>

313

Specify the maximum transfer rate you want curl to use. This feature is useful if you have a limited pipe and you'd like your transfer not use your entire bandwidth.

314

The given speed is measured in bytes/second, unless a suffix is appended. Appending 'k' or 'K' will count the number as kilobytes, 'm' or M' makes it megabytes while 'g' or 'G' makes it gigabytes. Examples: 200K, 3m and 1G.

315

The given rate is the average speed, counted during the entire transfer. It means that curl might use higher transfer speeds in short bursts, but over time it uses no more than the given rate.

316

If you are also using the <a class="emphasis" href="#-Y--speed-limit">-Y/--speed-limit</a> option, that option will take precedence and might cripple the rate-limiting slightly, to help keeping the speed-limit logic working.

298

Specify the maximum transfer rate you want curl to use. This feature is useful if you have a limited pipe and you'd like your transfer not to use your entire bandwidth.

299

The given speed is measured in bytes/second, unless a suffix is appended. Appending 'k' or 'K' will count the number as kilobytes, 'm' or M' makes it megabytes, while 'g' or 'G' makes it gigabytes. Examples: 200K, 3m and 1G.

300

The given rate is the average speed counted during the entire transfer. It means that curl might use higher transfer speeds in short bursts, but over time it uses no more than the given rate.

301

If you also use the <a class="emphasis" href="#-Y--speed-limit">-Y/--speed-limit</a> option, that option will take precedence and might cripple the rate-limiting slightly, to help keeping the speed-limit logic working.

317

302

If this option is used several times, the last one will be used.

318

303

<a name="-l--list-only"></a>-l/--list-only

319

304

(FTP) When listing an FTP directory, this switch forces a name-only view. Especially useful if you want to machine-parse the contents of an FTP directory since the normal directory view doesn't use a standard look or format.

320

305

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.

321

If this option is used twice, the second will again disable list only.

306

322

307

<a name="--local-port"></a>--local-port <num>[-num]

323

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 will be busy at times so setting this range to something too narrow might cause unnecessary connection setup failures. (Added in 7.15.2)

308

Set a preferred number or range of local port numbers to use for the connection(s). Note that port numbers by nature are 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)

324

309

<a name="-L--location"></a>-L/--location

325

(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.

310

(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.

326

311

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.

327

If this option is used twice, the second will again disable location following.

328

312

<a name="--location-trusted"></a>--location-trusted

329

(HTTP/HTTPS) Like <a class="emphasis" href="#-L--location">-L/--location</a>, but will allow sending the name + password to all hosts that the site may redirect to. This may or may not 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).

330

If this option is used twice, the second will again disable location following.

313

(HTTP/HTTPS) Like <a class="emphasis" href="#-L--location">-L/--location</a>, but will allow sending the name + password to all hosts that the site may redirect to. This may or may not introduce a security breach if the site redirects you to a site to which you'll send your authentication info (which is plaintext in the case of HTTP Basic authentication).

314

331

315

<a name="--max-filesize"></a>--max-filesize <bytes>

332

316

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.

333

NOTE: 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.

317

NOTE: 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.

334

318

335

319

Maximum time in seconds that you allow the whole operation to take. This is useful for preventing your batch jobs from hanging for hours due to slow networks or links going down. See also the <a class="emphasis" href="#--connect-timeout">--connect-timeout</a> option.

336

320

If this option is used several times, the last one will be used.

337

321

<a name="-M--manual"></a>-M/--manual

338

322

Manual. Display the huge help text.

339

323

<a name="-n--netrc"></a>-n/--netrc

340

Makes curl scan the .netrc file in the user's home directory for login name and password. This is typically used for ftp on unix. If used with http, curl will enable user authentication. See netrc(4) or ftp(1) for details on the file format. Curl will not complain if that file hasn't the right permissions (it should not be world nor group readable). The environment variable "HOME" is used to find the home directory.

341

A quick and very simple example of how to setup a .netrc to allow curl to ftp to the machine host.domain.com with user name 'myself' and password 'secret' should look similar to:

324

Makes curl scan the .netrc (_netrc on Windows) file in the user's home directory for login name and password. This is typically used for FTP on UNIX. If used with HTTP, curl will enable user authentication. See netrc(4) or ftp(1) for details on the file format. Curl will not complain if that file doesn't have the right permissions (it should not be either world- or group-readable). The environment variable "HOME" is used to find the home directory.

325

A quick and very simple example of how to setup a .netrc to allow curl to FTP to the machine host.domain.com with user name 'myself' and password 'secret' should look similar to:

342

326

machine host.domain.com login myself password secret

343

If this option is used twice, the second will again disable netrc usage.

344

327

<a name="--netrc-optional"></a>--netrc-optional

345

Very similar to --netrc, but this option makes the .netrc usage optional and not mandatory as the --netrc does.

328

346

329

<a name="--negotiate"></a>--negotiate

347

(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.

330

(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 method. For more information see IETF draft draft-brezak-spnego-http-04.txt.

348

331

If you want to enable Negotiate for your proxy authentication, then use <a class="emphasis" href="#--proxy-negotiate">--proxy-negotiate</a>.

349

This option requires that the library was built with GSSAPI support. This is not very common. Use <a class="emphasis" href="#-V--version">-V/--version</a> to see if your version supports GSS-Negotiate.

332

This option requires a library built with GSSAPI support. This is not very common. Use <a class="emphasis" href="#-V--version">-V/--version</a> to see if your version supports GSS-Negotiate.

350

333

When using this option, you must also provide a fake -u/--user option to activate the authentication code properly. Sending a '-u :' is enough as the user name and password from the -u option aren't actually used.

351

334

If this option is used several times, the following occurrences make no difference.

352

335

<a name="-N--no-buffer"></a>-N/--no-buffer

353

336

Disables the buffering of the output stream. In normal work situations, curl 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.

354

If this option is used twice, the second will again switch on buffering.

337

Note that this is the negated option name documented. You can thus use --buffer to enforce the buffering.

355

338

<a name="--no-keepalive"></a>--no-keepalive

356

339

Disables the use of keepalive messages on the TCP connection, as by default curl enables them.

357

If this option is used twice, the second will again enable keepalive.

340

Note that this is the negated option name documented. You can thus use --keepalive to enforce keepalive.

358

341

<a name="--no-sessionid"></a>--no-sessionid

359

(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 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)

360

If this option is used twice, the second will again switch on use of the session cache.

342

(SSL) Disable curl's use of SSL session-ID caching. By default all transfers are done using the cache. Note that while nothing should ever get hurt by 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)

343

Note that this is the negated option name documented. You can thus use --sessionid to enforce session-ID caching.

344

<a name="--noproxy"></a>--noproxy <no-proxy-list>

345

Comma-separated list of hosts which do not use a proxy, if one is specified. The only wildcard is a single * character, which matches all hosts, and effectively disables the proxy. Each name in this list is matched as either a domain which contains the hostname, or the hostname itself. For example, local.com would match local.com, local.com:80, and www.local.com, but not www.notlocal.com. (Added in 7.19.4).

361

346

<a name="--ntlm"></a>--ntlm

362

(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.

347

(HTTP) Enables NTLM authentication. The NTLM authentication method was designed by Microsoft and is used by IIS web servers. It is a proprietary protocol, reverse-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.

363

348

If you want to enable NTLM for your proxy authentication, then use <a class="emphasis" href="#--proxy-ntlm">--proxy-ntlm</a>.

364

This option requires that the library was built with SSL support. Use <a class="emphasis" href="#-V--version">-V/--version</a> to see if your curl supports NTLM.

349

This option requires a library built with SSL support. Use <a class="emphasis" href="#-V--version">-V/--version</a> to see if your curl supports NTLM.

365

350

If this option is used several times, the following occurrences make no difference.

366

351

<a name="-o--output"></a>-o/--output <file>

367

352

Write output to <file> instead of stdout. If you are using {} or [] to fetch multiple documents, you can use '#' followed by a number in the <file> specifier. That variable will be replaced with the current string for the URL being fetched. Like in:

368

353

curl http://{one,two}.site.com -o "file_#1.txt"

369

354

or use several variables like:

370

355

curl http://{site,host}.host[1-5].com -o "#1_#2"

371

You may use this option as many times as you have number of URLs.

372

See also the <a class="emphasis" href="#--create-dirs">--create-dirs</a> option to create the local directories dynamically.

356

You may use this option as many times as the number of URLs you have.

357

See also the <a class="emphasis" href="#--create-dirs">--create-dirs</a> option to create the local directories dynamically. Specifying the output as '-' (a single dash) will force the output to be done to stdout.

373

358

<a name="-O--remote-name"></a>-O/--remote-name

374

359

Write output to a local file named like the remote file we get. (Only the file part of the remote file is used, the path is cut off.)

375

360

The remote file name to use for saving is extracted from the given URL, nothing else.

376

You may use this option as many times as you have number of URLs.

361

You may use this option as many times as the number of URLs you have.

362

<a name="--remote-name-all"></a>--remote-name-all

363

This option changes the default action for all given URLs to be dealt with as if <a class="emphasis" href="#-O--remote-name">-O/--remote-name</a> were used for each one. So if you want to disable that for a specific URL after <a class="emphasis" href="#--remote-name-all">--remote-name-all</a> has been used, you must use "-o -" or --no-remote-name. (Added in 7.19.0)

377

364

378

(SSL/SSH) Pass phrase for the private key

365

(SSL/SSH) Passphrase for the private key

379

366

If this option is used several times, the last one will be used.

380

367

<a name="--post301"></a>--post301

381

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 requires a POST to remain a POST after such a redirection. This option is meaningful only when using <a class="emphasis" href="#-L--location">-L/--location</a> (Added in 7.17.1)

368

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 <a class="emphasis" href="#-L--location">-L/--location</a> (Added in 7.17.1)

369

<a name="--post302"></a>--post302

370

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 <a class="emphasis" href="#-L--location">-L/--location</a> (Added in 7.19.1)

382

371

<a name="--proxy-anyauth"></a>--proxy-anyauth

383

372

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)

384

If this option is used twice, the second will again disable the proxy use-any authentication.

385

373

<a name="--proxy-basic"></a>--proxy-basic

386

374

Tells curl to use HTTP Basic authentication when communicating with the given proxy. Use <a class="emphasis" href="#--basic">--basic</a> for enabling HTTP Basic with a remote host. Basic is the default authentication method curl uses with proxies.

387

If this option is used twice, the second will again disable proxy HTTP Basic authentication.

388

375

<a name="--proxy-digest"></a>--proxy-digest

389

376

Tells curl to use HTTP Digest authentication when communicating with the given proxy. Use <a class="emphasis" href="#--digest">--digest</a> for enabling HTTP Digest with a remote host.

390

If this option is used twice, the second will again disable proxy HTTP Digest.

391

377

<a name="--proxy-negotiate"></a>--proxy-negotiate

392

Tells curl to use HTTP Negotiate authentication when communicating with the given proxy. Use <a class="emphasis" href="#--negotiate">--negotiate</a> for enabling HTTP Negotiate with a remote host.

393

If this option is used twice, the second will again disable proxy HTTP Negotiate. (Added in 7.17.1)

378

394

379

<a name="--proxy-ntlm"></a>--proxy-ntlm

395

380

Tells curl to use HTTP NTLM authentication when communicating with the given proxy. Use <a class="emphasis" href="#--ntlm">--ntlm</a> for enabling NTLM with a remote host.

396

If this option is used twice, the second will again disable proxy HTTP NTLM.

381

<a name="--proxy10"></a>--proxy1.0 <proxyhost[:port]>

382

Use the specified HTTP 1.0 proxy. If the port number is not specified, it is assumed at port 1080.

383

The only difference between this and the HTTP proxy option (<a class="emphasis" href="#-x--proxy">-x/--proxy</a>), is that attempts to use CONNECT through the proxy will specify an HTTP 1.0 protocol instead of the default HTTP 1.1.

397

384

<a name="-p--proxytunnel"></a>-p/--proxytunnel

398

385

When an HTTP proxy is used (<a class="emphasis" href="#-x--proxy">-x/--proxy</a>), 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.

399

If this option is used twice, the second will again disable proxy tunnel.

400

386

<a name="--pubkey"></a>--pubkey <key>

401

387

(SSH) Public key file name. Allows you to provide your public key in this separate file.

402

388

If this option is used several times, the last one will be used.

403

389

404

(FTP) Reverses the initiator/listener roles when connecting with ftp. This switch makes Curl use the PORT command instead of PASV. In practise, PORT tells the server to connect to the client's specified address and port, while PASV asks the server for an ip address and port to connect to. <address> should be one of:

390

(FTP) Reverses the default initiator/listener roles when connecting with FTP. This switch makes curl use active mode. In practice, 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:

405

391

406

392

<a name="interface"></a>interface

407

i.e "eth0" to specify which interface's IP address you want to use (Unix only)

393

i.e "eth0" to specify which interface's IP address you want to use (Unix only)

408

394

<a name="IP"></a>IP address

409

i.e "192.168.10.1" to specify exact IP number

395

i.e "192.168.10.1" to specify the exact IP address

410

396

<a name="host"></a>host name

411

i.e "my.host.domain" to specify machine

397

i.e "my.host.domain" to specify the machine

412

398

<a name="-"></a>-

413

399

make curl pick the same IP address that is already used for the control connection

414

400

416

402

<a name="-q"></a>-q

417

403

If used as the first parameter on the command line, the curlrc config file will not be read and used. See the <a class="emphasis" href="#-K--config">-K/--config</a> for details on the default config file search path.

418

404

<a name="-Q--quote"></a>-Q/--quote <command>

419

(FTP/SFTP) Send an arbitrary command to the remote FTP or SFTP server. Quote commands are sent BEFORE the transfer is taking 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 get sent after libcurl has changed working directory, just before the transfer command(s), prefix the command with '+' (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 RFC959 defines to FTP servers, or one of the following commands (with appropriate arguments) to SFTP servers: chgrp, chmod, chown, ln, mkdir, pwd, rename, rm, rmdir, symlink.

420

This option can be used multiple times.

405

(FTP/SFTP) Send an arbitrary command to the remote FTP or SFTP server. Quote 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 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 RFC959 defines to FTP servers, or one of the commands listed below to SFTP servers. This option can be used multiple times.

406

SFTP is a binary protocol. Unlike for FTP, libcurl interprets SFTP quote commands before sending them to the server. Following is the list of all supported SFTP quote commands:

407

408

<a name="chgrp"></a>chgrp group file

409

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.

410

<a name="chmod"></a>chmod mode file

411

The chmod command modifies the file mode bits of the specified file. The mode operand is an octal integer mode number.

412

<a name="chown"></a>chown user file

413

The chown command sets the owner of the file named by the file operand to the user ID specified by the user operand. The user operand is a decimal integer user ID.

414

<a name="ln"></a>ln source_file target_file

415

The ln and symlink commands create a symbolic link at the target_file location pointing to the source_file location.

416

<a name="mkdir"></a>mkdir directory_name

417

The mkdir command creates the directory named by the directory_name operand.

418

<a name="pwd"></a>pwd

419

The pwd command returns the absolute pathname of the current working directory.

420

<a name="rename"></a>rename source target

421

The rename command renames the file or directory named by the source operand to the destination path named by the target operand.

422

<a name="rm"></a>rm file

423

The rm command removes the file specified by the file operand.

424

<a name="rmdir"></a>rmdir directory

425

The rmdir command removes the directory entry specified by the directory operand, provided it is empty.

426

<a name="symlink"></a>symlink source_file target_file

427

See ln.

428

421

429

<a name="--random-file"></a>--random-file <file>

422

430

(SSL) Specify the path name to file containing what will be considered as random data. The data is used to seed the random engine for SSL connections. See also the <a class="emphasis" href="#--egd-file">--egd-file</a> option.

423

431

<a name="-r--range"></a>-r/--range <range>

424

(HTTP/FTP/FILE) Retrieve a byte range (i.e a partial document) from a HTTP/1.1, FTP server or a local FILE. Ranges can be specified in a number of ways.

432

(HTTP/FTP/SFTP/FILE) Retrieve a byte range (i.e a partial document) from a HTTP/1.1, FTP or SFTP server or a local FILE. Ranges can be specified in a number of ways.

425

433

426

434

0-499 specifies the first 500 bytes

427

435

500-999 specifies the second 500 bytes

429

437

9500- specifies the bytes from offset 9500 and forward

430

438

0-0,-1 specifies the first and last byte only(*)(H)

431

439

500-700,600-799 specifies 300 bytes from offset 500(H)

432

100-199,500-599 specifies two separate 100 bytes ranges(*)(H)

440

100-199,500-599 specifies two separate 100-byte ranges(*)(H)

433

441

434

442

(*) = NOTE that this will cause the server to reply with a multipart response!

435

Only digit characters (0-9) are valid in 'start' and 'stop' of range syntax 'start-stop'. If a non-digit character is given in the range, the server's response will be indeterminable, depending on different server's configuration.

443

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.

436

444

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 document.

437

FTP range downloads only support the simple syntax 'start-stop' (optionally with one of the numbers omitted). It depends on the non-RFC command SIZE.

445

FTP and SFTP range downloads only support the simple 'start-stop' syntax (optionally with one of the numbers omitted). FTP use depends on the extended FTP command SIZE.

438

446

If this option is used several times, the last one will be used.

439

447

<a name="--raw"></a>--raw

440

448

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)

441

If this option is used several times, each occurrence toggles this on/off.

442

449

<a name="-R--remote-time"></a>-R/--remote-time

443

450

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.

444

If this option is used twice, the second time disables this again.

445

451

<a name="--retry"></a>--retry <num>

446

452

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 makes curl do no retries (which is the default). Transient error means either: a timeout, an FTP 5xx response code or an HTTP 5xx response code.

447

453

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)

448

454

If this option is used multiple times, the last occurrence decide the amount.

449

455

<a name="--retry-delay"></a>--retry-delay <seconds>

450

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)

451

If this option is used multiple times, the last occurrence decide the amount.

456

Make curl sleep this amount of time before 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)

457

If this option is used multiple times, the last occurrence determines the amount.

452

458

<a name="--retry-max-time"></a>--retry-max-time <seconds>

453

459

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´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)

454

If this option is used multiple times, the last occurrence decide the amount.

460

If this option is used multiple times, the last occurrence determines the amount.

455

461

<a name="-s--silent"></a>-s/--silent

456

462

Silent mode. Don't show progress meter or error messages. Makes Curl mute.

457

If this option is used twice, the second will again disable silent mode.

458

463

<a name="-S--show-error"></a>-S/--show-error

459

When used with -s it makes curl show error message if it fails.

460

If this option is used twice, the second will again disable show error.

464

When used with -s it makes curl show an error message if it fails.

461

465

<a name="--socks4"></a>--socks4 <host[:port]>

462

466

Use the specified SOCKS4 proxy. If the port number is not specified, it is assumed at port 1080. (Added in 7.15.2)

463

467

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

474

478

Use the specified SOCKS5 proxy - but resolve the host name locally. If the port number is not specified, it is assumed at port 1080.

475

479

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

476

480

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.)

481

<a name="--socks5-gssapi-service"></a>--socks5-gssapi-service <servicename>

482

The default service name for a socks server is rcmd/server-fqdn. This option allows you to change it.

483

Examples:  --socks5 proxy-name <a class="emphasis" href="#--socks5-gssapi-service">--socks5-gssapi-service</a> sockd would use sockd/proxy-name  --socks5 proxy-name <a class="emphasis" href="#--socks5-gssapi-service">--socks5-gssapi-service</a> sockd/real-name would use sockd/real-name for cases where the proxy-name does not match the princpal name.  (Added in 7.19.4).

484

<a name="--socks5-gssapi-nec"></a>--socks5-gssapi-nec

485

As part of the gssapi negotiation a protection mode is negotiated. The rfc1961 says in section 4.3/4.4 it should be protected, but the NEC reference implementation does not. The option <a class="emphasis" href="#--socks5-gssapi-nec">--socks5-gssapi-nec</a> allows the unprotected exchange of the protection mode negotiation. (Added in 7.19.4).

477

486

<a name="--stderr"></a>--stderr <file>

478

487

Redirect all writes to stderr to the specified file instead. If the file name is a plain '-', it is instead written to stdout. This option has no point when you're using a shell with decent redirecting capabilities.

479

488

If this option is used several times, the last one will be used.

480

489

<a name="--tcp-nodelay"></a>--tcp-nodelay

481

490

Turn on the TCP_NODELAY option. See the curl_easy_setopt(3) man page for details about this option. (Added in 7.11.2)

482

If this option is used several times, each occurrence toggles this on/off.

483

491

<a name="-t--telnet-option"></a>-t/--telnet-option <OPT=val>

484

492

Pass options to the telnet protocol. Supported options are:

485

493

TTYPE=<term> Sets the terminal type.

486

494

XDISPLOC=<X display> Sets the X display location.

487

495

NEW_ENV=<var,val> Sets an environment variable.

488

496

<a name="-T--upload-file"></a>-T/--upload-file <file>

489

This transfers the specified local file to the remote URL. If there is no file part in the specified URL, Curl will append the local file name. NOTE that you must use a trailing / on the last directory to really prove to Curl that there is no file name or curl will think that your last directory name is the remote file name to use. That will most likely cause the upload operation to fail. If this is used on a http(s) server, the PUT command will be used.

497

490

498

Use the file name "-" (a single dash) to use stdin instead of a given file.

491

499

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:

492

500

curl -T "{file1,file2}" <a href="http://www.uploadtothissite.com">http://www.uploadtothissite.com</a>

503

511

If this option is used several times, the last one will be used.

504

512

<a name="--trace-time"></a>--trace-time

505

513

Prepends a time stamp to each trace or verbose line that curl displays. (Added in 7.14.0)

506

If this option is used several times, each occurrence will toggle it on/off.

507

514

508

Specify user and password to use for server authentication. Overrides <a class="emphasis" href="#-n--netrc">-n/--netrc</a> and <a class="emphasis" href="#--netrc-optional">--netrc-optional</a>.

515

Specify the user name and password to use for server authentication. Overrides <a class="emphasis" href="#-n--netrc">-n/--netrc</a> and <a class="emphasis" href="#--netrc-optional">--netrc-optional</a>.

509

516

If you just give the user name (without entering a colon) curl will prompt for a password.

510

517

If you use an SSPI-enabled curl binary and do NTLM authentication, you can force curl to pick up the user name and password from your environment by simply specifying a single colon with this option: "-u :".

511

518

If this option is used several times, the last one will be used.

512

519

<a name="-U--proxy-user"></a>-U/--proxy-user <user:password>

513

Specify user and password to use for proxy authentication.

520

Specify the user name and password to use for proxy authentication.

514

521

515

522

If this option is used several times, the last one will be used.

516

523

517

524

Specify a URL to fetch. This option is mostly handy when you want to specify URL(s) in a config file.

518

525

This option may be used any number of times. To control where this URL is written, use the <a class="emphasis" href="#-o--output">-o/--output</a> or the <a class="emphasis" href="#-O--remote-name">-O/--remote-name</a> options.

519

526

<a name="-v--verbose"></a>-v/--verbose

520

Makes the fetching more verbose/talkative. Mostly usable for debugging. Lines starting with '>' means "header data" sent by curl, '<' means "header data" received by curl that is hidden in normal cases and lines starting with '*' means additional info provided by curl.

521

Note that if you only want HTTP headers in the output, <a class="emphasis" href="#-i--include">-i/--include</a> might be option you're looking for.

527

Makes the fetching more verbose/talkative. Mostly useful for debugging. 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.

528

Note that if you only want HTTP headers in the output, <a class="emphasis" href="#-i--include">-i/--include</a> might be the option you're looking for.

522

529

If you think this option still doesn't give you enough details, consider using <a class="emphasis" href="#--trace">--trace</a> or <a class="emphasis" href="#--trace-ascii">--trace-ascii</a> instead.

523

530

This option overrides previous uses of <a class="emphasis" href="#--trace-ascii">--trace-ascii</a> or <a class="emphasis" href="#--trace">--trace</a>.

524

If this option is used twice, the second will do nothing extra.

525

531

<a name="-V--version"></a>-V/--version

526

532

Displays information about curl and the libcurl version it uses.

527

533

The first line includes the full version of curl, libcurl and other 3rd party libraries linked with the executable.

531

537

<a name="IPv6"></a>IPv6

532

538

You can use IPv6 with this.

533

539

<a name="krb4"></a>krb4

534

Krb4 for ftp is supported.

540

Krb4 for FTP is supported.

535

541

<a name="SSL"></a>SSL

536

542

HTTPS and FTPS are supported.

537

543

<a name="libz"></a>libz

539

545

<a name="NTLM"></a>NTLM

540

546

NTLM authentication is supported.

541

547

<a name="GSS-Negotiate"></a>GSS-Negotiate

542

Negotiate authentication and krb5 for ftp is supported.

548

Negotiate authentication and krb5 for FTP is supported.

543

549

<a name="Debug"></a>Debug

544

550

This curl uses a libcurl built with Debug. This enables more error-tracking and memory debugging etc. For curl-developers only!

545

551

<a name="AsynchDNS"></a>AsynchDNS

555

561

556

562

<a name="-w--write-out"></a>-w/--write-out <format>

557

563

Defines what to display on stdout after a completed and successful operation. The format is a string that may contain plain text mixed with any number of variables. The string can be specified as "string", to get read from a particular file you specify it "@filename" and to tell curl to read the format from stdin you write "@-".

558

The variables present in the output format will be substituted by the value or text that curl thinks fit, as described below. All variables are specified like %{variable_name} and to output a normal % you just write them like %%. You can output a newline by using \n, a carriage return with \r and a tab space with \t.

559

NOTE: The %-letter is a special letter in the win32-environment, where all occurrences of % must be doubled when using this option.

560

Available variables are at this point:

564

The variables present in the output format will be substituted by the value or text that curl thinks fit, as described below. All variables are specified as %{variable_name} and to output a normal % you just write them as %%. You can output a newline by using \n, a carriage return with \r and a tab space with \t.

565

NOTE: The %-symbol is a special symbol in the win32-environment, where all occurrences of % must be doubled when using this option.

566

The variables available at this point are:

561

567

562

url_effective The URL that was fetched last. This is mostly meaningful if you've told curl to follow location: headers.

568

url_effective The URL that was fetched last. This is most meaningful if you've told curl to follow location: headers.

563

569

http_code The numerical response code that was found in the last retrieved HTTP(S) or FTP(s) transfer. In 7.18.2 the alias response_code was added to show the same info.

564

570

http_connect The numerical code that was found in the last response (from a proxy) to a curl CONNECT request. (Added in 7.12.4)

565

571

time_total The total time, in seconds, that the full operation lasted. The time will be displayed with millisecond resolution.

566

572

time_namelookup The time, in seconds, it took from the start until the name resolving was completed.

567

time_connect The time, in seconds, it took from the start until the connect to the remote host (or proxy) was completed.

568

time_pretransfer The time, in seconds, it took from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved.

569

time_redirect The time, in seconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started. time_redirect shows the complete execution time for multiple redirections. (Added in 7.12.3)

570

time_starttransfer The time, in seconds, it took from the start until the first byte is just about to be transferred. This includes time_pretransfer and also the time the server needs to calculate the result.

573

time_connect The time, in seconds, it took from the start until the TCP connect to the remote host (or proxy) was completed.

574

time_appconnect The time, in seconds, it took from the start until the SSL/SSH/etc connect/handshake to the remote host was completed. (Added in 7.19.0)

575

time_pretransfer The time, in seconds, it took from the start until the file transfer was just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved.

576

time_redirect The time, in seconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer before the final transaction was started. time_redirect shows the complete execution time for multiple redirections. (Added in 7.12.3)

577

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 server needed to calculate the result.

571

578

size_download The total amount of bytes that were downloaded.

572

579

size_upload The total amount of bytes that were uploaded.

573

580

size_header The total amount of bytes of the downloaded headers.

579

586

num_redirects Number of redirects that were followed in the request. (Added in 7.12.3)

580

587

redirect_url When a HTTP request was made without -L to follow redirects, this variable will show the actual URL a redirect would take you to. (Added in 7.18.2)

581

588

ftp_entry_path The initial path libcurl ended up in when logging on to the remote FTP server. (Added in 7.15.4)

589

ssl_verify_result The result of the SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.19.0)

582

590

583

591

If this option is used several times, the last one will be used.

584

592

<a name="-x--proxy"></a>-x/--proxy <proxyhost[:port]>

585

Use specified HTTP proxy. If the port number is not specified, it is assumed at port 1080.

586

This option overrides existing environment variables that sets proxy to use. If there's an environment variable setting a proxy, you can set proxy to "" to override it.

593

Use the specified HTTP proxy. If the port number is not specified, it is assumed at port 1080.

594

This option overrides existing environment variables that set the proxy to use. If there's an environment variable setting a proxy, you can set proxy to "" to override it.

587

595

Note that all operations that are performed over a HTTP proxy will transparently be converted to HTTP. It means that certain protocol specific operations might not be available. This is not the case if you can tunnel through the proxy, as done with the <a class="emphasis" href="#-p--proxytunnel">-p/--proxytunnel</a> option.

588

Starting with 7.14.1, the proxy host can be specified the exact same way as the proxy environment variables, include protocol prefix (http://) and embedded user + password.

596

Starting with 7.14.1, the proxy host can be specified the exact same way as the proxy environment variables, including the protocol prefix (http://) and the embedded user + password.

589

597

If this option is used several times, the last one will be used.

590

598

<a name="-X--request"></a>-X/--request <command>

591

599

(HTTP) Specifies a custom request method to use when communicating with the HTTP server. The specified request will be used instead of the method otherwise used (which defaults to GET). Read the HTTP 1.1 specification for details and explanations.

592

(FTP) Specifies a custom FTP command to use instead of LIST when doing file lists with ftp.

600

(FTP) Specifies a custom FTP command to use instead of LIST when doing file lists with FTP.

593

601

If this option is used several times, the last one will be used.

594

602

<a name="-y--speed-time"></a>-y/--speed-time <time>

595

If a download is slower than speed-limit bytes per second during a speed-time period, the download gets aborted. If speed-time is used, the default speed-limit will be 1 unless set with -y.

603

596

604

This option controls transfers and thus will not affect slow connects etc. If this is a concern for you, try the <a class="emphasis" href="#--connect-timeout">--connect-timeout</a> option.

597

605

If this option is used several times, the last one will be used.

598

606

<a name="-Y--speed-limit"></a>-Y/--speed-limit <speed>

599

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 -Y and is 30 if not set.

607

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 -y and is 30 if not set.

600

608

If this option is used several times, the last one will be used.

601

609

602

610

(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 tries to get the time from a given file name instead! See the curl_getdate(3) man pages for date expression details.

608

616

<a name="-0--http10"></a>-0/--http1.0

609

617

(HTTP) Forces curl to issue its requests using HTTP 1.0 instead of using its internally preferred: HTTP 1.1.

610

618

<a name="-1--tlsv1"></a>-1/--tlsv1

611

(SSL) Forces curl to use TSL version 1 when negotiating with a remote TLS server.

619

(SSL) Forces curl to use TLS version 1 when negotiating with a remote TLS server.

612

620

<a name="-2--sslv2"></a>-2/--sslv2

613

621

(SSL) Forces curl to use SSL version 2 when negotiating with a remote SSL server.

614

622

<a name="-3--sslv3"></a>-3/--sslv3

615

623

(SSL) Forces curl to use SSL version 3 when negotiating with a remote SSL server.

616

624

<a name="-4--ipv4"></a>-4/--ipv4

617

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.

625

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.

618

626

<a name="-6--ipv6"></a>-6/--ipv6

619

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.

627

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.

620

628

<a name="---progress-bar"></a>-#/--progress-bar

621

Make curl display progress information as a progress bar instead of the default statistics.

622

If this option is used twice, the second will again disable the progress bar. <a name="FILES"></a><h2 class="nroffsh">FILES</h2>

629

Make curl display progress information as a progress bar instead of the default statistics. <a name="FILES"></a><h2 class="nroffsh">FILES</h2>

623

630

~/.curlrc

624

Default config file, see <a class="emphasis" href="#-K--config">-K/--config</a> for details.

625

<a name="ENVIRONMENT"></a><h2 class="nroffsh">ENVIRONMENT</h2>

626

631

Default config file, see <a class="emphasis" href="#-K--config">-K/--config</a> for details. <a name="ENVIRONMENT"></a><h2 class="nroffsh">ENVIRONMENT</h2>

632

The environment variables can be specified in lower case or upper case. The lower case version has precedence. http_proxy is an exception as it is only available in lower case.

627

633

<a name="httpproxy"></a>http_proxy [protocol://]<host>[:port]

628

Sets proxy server to use for HTTP.

634

Sets the proxy server to use for HTTP.

629

635

<a name="HTTPSPROXY"></a>HTTPS_PROXY [protocol://]<host>[:port]

630

Sets proxy server to use for HTTPS.

636

Sets the proxy server to use for HTTPS.

631

637

<a name="FTPPROXY"></a>FTP_PROXY [protocol://]<host>[:port]

632

Sets proxy server to use for FTP.

638

Sets the proxy server to use for FTP.

633

639

<a name="ALLPROXY"></a>ALL_PROXY [protocol://]<host>[:port]

634

Sets proxy server to use if no protocol-specific proxy is set.

640

Sets the proxy server to use if no protocol-specific proxy is set.

635

641

<a name="NOPROXY"></a>NO_PROXY <comma-separated list of hosts>

636

642

list of host names that shouldn't go through any proxy. If set to a asterisk '*' only, it matches all hosts. <a name="EXIT"></a><h2 class="nroffsh">EXIT CODES</h2>

637

There exists a bunch of different error codes and their corresponding error messages that may appear during bad conditions. At the time of this writing, the exit codes are:

643

There are a bunch of different error codes and their corresponding error messages that may appear during bad conditions. At the time of this writing, the exit codes are:

638

644

<a name="1"></a>1

639

645

Unsupported protocol. This build of curl has no support for this protocol.

640

646

<a name="2"></a>2

641

647

Failed to initialize.

642

648

<a name="3"></a>3

643

URL malformat. The syntax was not correct.

649

URL malformed. The syntax was not correct.

644

650

<a name="5"></a>5

645

651

Couldn't resolve proxy. The given proxy host could not be resolved.

646

652

<a name="6"></a>6

712

718

<a name="49"></a>49

713

719

Malformed telnet option.

714

720

<a name="51"></a>51

715

The peer's SSL certificate or SSH MD5 fingerprint was not ok

721

The peer's SSL certificate or SSH MD5 fingerprint was not ok.

716

722

<a name="52"></a>52

717

723

The server didn't reply anything, which here is considered an error.

718

724

<a name="53"></a>53

719

SSL crypto engine not found

725

SSL crypto engine not found.

720

726

<a name="54"></a>54

721

Cannot set SSL crypto engine as default

727

Cannot set SSL crypto engine as default.

722

728

<a name="55"></a>55

723

Failed sending network data

729

Failed sending network data.

724

730

<a name="56"></a>56

725

Failure in receiving network data

731

Failure in receiving network data.

726

732

<a name="58"></a>58

727

Problem with the local certificate

733

Problem with the local certificate.

728

734

<a name="59"></a>59

729

Couldn't use specified SSL cipher

735

Couldn't use specified SSL cipher.

730

736

<a name="60"></a>60

731

Peer certificate cannot be authenticated with known CA certificates

737

Peer certificate cannot be authenticated with known CA certificates.

732

738

<a name="61"></a>61

733

Unrecognized transfer encoding

739

Unrecognized transfer encoding.

734

740

<a name="62"></a>62

735

Invalid LDAP URL

741

Invalid LDAP URL.

736

742

<a name="63"></a>63

737

Maximum file size exceeded

743

Maximum file size exceeded.

738

744

<a name="64"></a>64

739

Requested FTP SSL level failed

745

Requested FTP SSL level failed.

740

746

<a name="65"></a>65

741

Sending the data requires a rewind that failed

747

Sending the data requires a rewind that failed.

742

748

<a name="66"></a>66

743

Failed to initialise SSL Engine

749

Failed to initialise SSL Engine.

744

750

<a name="67"></a>67

745

User, password or similar was not accepted and curl failed to login

751

The user name, password, or similar was not accepted and curl failed to log in.

746

752

<a name="68"></a>68

747

File not found on TFTP server

753

File not found on TFTP server.

748

754

<a name="69"></a>69

749

Permission problem on TFTP server

755

Permission problem on TFTP server.

750

756

<a name="70"></a>70

751

Out of disk space on TFTP server

757

Out of disk space on TFTP server.

752

758

<a name="71"></a>71

753

Illegal TFTP operation

759

Illegal TFTP operation.

754

760

<a name="72"></a>72

755

Unknown TFTP transfer ID

761

Unknown TFTP transfer ID.

756

762

<a name="73"></a>73

757

File already exists (TFTP)

763

File already exists (TFTP).

758

764

<a name="74"></a>74

759

No such user (TFTP)

765

No such user (TFTP).

760

766

<a name="75"></a>75

761

Character conversion failed

767

Character conversion failed.

762

768

<a name="76"></a>76

763

Character conversion functions required

769

Character conversion functions required.

764

770

<a name="77"></a>77

765

Problem with reading the SSL CA cert (path? access rights?)

771

Problem with reading the SSL CA cert (path? access rights?).

766

772

<a name="78"></a>78

767

The resource referenced in the URL does not exist

773

The resource referenced in the URL does not exist.

768

774

<a name="79"></a>79

769

An unspecified error occurred during the SSH session

775

An unspecified error occurred during the SSH session.

770

776

<a name="80"></a>80

771

Failed to shut down the SSL connection

777

Failed to shut down the SSL connection.

778

<a name="82"></a>82

779

Could not load CRL file, missing or wrong format (added in 7.19.0).

780

<a name="83"></a>83

781

Issuer check failed (added in 7.19.0).

772

782

<a name="XX"></a>XX

773

There will appear more error codes here in future releases. The existing ones are meant to never change. <a name="AUTHORS"></a><h2 class="nroffsh">AUTHORS / CONTRIBUTORS</h2>

783

More error codes will appear here in future releases. The existing ones are meant to never change. <a name="AUTHORS"></a><h2 class="nroffsh">AUTHORS / CONTRIBUTORS</h2>

774

784

Daniel Stenberg is the main author, but the whole list of contributors is found in the separate THANKS file. <a name="WWW"></a><h2 class="nroffsh">WWW</h2>

775

785

776

786

<a href="ftp://ftp.sunet.se/pub/www/utilities/curl/">ftp://ftp.sunet.se/pub/www/utilities/curl/</a> <a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2>

Older »