Newer
Older
.\" You can view this file with:
.\" nroff -man curl.1
.\" Written by Daniel Stenberg
.\"
is a tool to transfer data from or to a server, using one of the supported
protocols (HTTP, HTTPS, FTP, FTPS, GOPHER, 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 (https:) connections, cookies, file
transfer resume and more. As you will see below, the amount of features will
make your head spin!
curl is powered by libcurl for all transfer-related features. See
.BR libcurl (3)
for details.
.SH URL
The URL syntax is protocol dependent. You'll find a detailed description in
RFC 2396.
You can specify multiple URLs or parts of URLs by writing part sets within
braces as in:
http://site.{one,two,three}.com
or you can get sequences of alphanumeric series by using [] as in:
ftp://ftp.numericals.com/file[1-100].txt
ftp://ftp.numericals.com/file[001-100].txt (with leading zeros)
ftp://ftp.letters.com/file[a-z].txt
It is possible to specify up to 9 sets or series for a URL, but no nesting is
supported at the moment:
http://www.any.org/archive[1996-1999]/volume[1-4]part{a,b,c,index}.html
You can specify any amount of URLs on the command line. They will be fetched
in a sequential manner in the specified order.
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.
(FTP) When used in an FTP upload, this will tell curl to append to the target
file instead of overwriting it. If the file doesn't exist, it will be created.
If this option is used twice, the second one will disable append mode again.
.IP "-A/--user-agent <agent string>"
(HTTP)
Specify the User-Agent string to send to the HTTP server. Some badly done CGIs
fail if its not 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
-H/--header flag of course.
If this option is set more than once, the last one will be the one that's
used.
.IP "--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 inducing an extra
network round-trip. This is used instead of setting a specific authentication
method, which you can do with \fI--digest\fP, \fI--ntlm\fP, and
\fI--negotiate\fP. (Added in 7.10.6)
If this option is used several times, the following occurrences make no
difference.
.IP "-b/--cookie <name=data>"
(HTTP)
Pass the data to the HTTP server as a cookie. It is supposedly the
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
Daniel Stenberg
committed
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 -L/--location option. The file format of the file to
read cookies from should be plain HTTP headers or the Netscape/Mozilla cookie
file format.
.B NOTE
that the file specified with -b/--cookie is only used as input. No cookies
will be stored in the file. To store cookies, save the HTTP headers to a file
using -D/--dump-header!
If this option is set more than once, the last one will be the one that's
used.
Use ASCII transfer when getting an FTP file or LDAP info. For FTP, this can
also be enforced by using an URL that ends with ";type=A". This option causes
data sent to stdout to be in text mode for win32 systems.
If this option is used twice, the second one will disable ASCII usage.
.IP "--basic"
(HTTP) Tells curl to use HTTP Basic authentication. This is the default and
this option is usually pointless, unless you use it to override a previously
set option that sets a different authentication method (such as \fI--ntlm\fP,
\fI--digest\fP and \fI--negotiate\fP). (Added in 7.10.6)
If this option is used several times, the following occurrences make no
difference.
.IP "--ciphers <list of ciphers>"
(SSL) Specifies which ciphers to use in the connection. The list of ciphers
must be using valid ciphers. Read up on SSL cipher list details on this URL:
.I http://www.openssl.org/docs/apps/ciphers.html (Option added in curl 7.9)
If this option is used several times, the last one will override the others.
(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.
.IP "--connect-timeout <seconds>"
Maximum time in seconds that you allow the connection to the server to take.
This only limits the connection phase, once curl has connected this option is
of no more use. See also the \fI--max-time\fP option.
If this option is used several times, the last one will be used.
.IP "-c/--cookie-jar <file name>"
Specify to which file you want curl to write all cookies after a completed
operation. Curl writes all cookies previously read from a specified file as
well as all cookies received from remote server(s). If no cookies are known,
no file will be written. The file will be written using the Netscape cookie
file format. If you set the file name to a single dash, "-", the cookies will
.B 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.
If this option is used several times, the last specfied file name will be
used.
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 transfered to the destination. If used with
uploads, the ftp server command SIZE will not be used by curl.
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.
If this option is used several times, the last one will be used.
When used in conjunction with the -o option, curl will create the necessary
local directory hierarchy as needed.
.IP "--crlf"
(FTP) Convert LF to CRLF in upload. Useful for MVS (OS/390).
If this option is used twice, the second will again disable crlf converting.
Daniel Stenberg
committed
(HTTP) Sends the specified data in a POST request to the HTTP server, in a way
that can emulate as if a user has filled in a HTML form and pressed the submit
button. Note that the data is sent exactly as specified with no extra
processing (with all newlines cut off). The data is expected to be
"url-encoded". This will cause curl to pass the data to the server using the
content-type application/x-www-form-urlencoded. Compare to -F. If more than
one -d/--data option is used 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'.
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".
To post data purely binary, you should instead use the --data-binary option.
-d/--data is the same as --data-ascii.
If this option is used several times, the ones following the first will
.IP "--data-ascii <data>"
(HTTP) This is an alias for the -d/--data option.
If this option is used several times, the ones following the first will
.IP "--data-binary <data>"
(HTTP) This posts data in a similar manner as --data-ascii does, although when
using this option the entire context of the posted data is kept as-is. If you
want to post a binary file without the strip-newlines feature of the
--data-ascii option, this is for you.
If this option is used several times, the ones following the first will
Loading
Loading full blame…