.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "curl 1"
.TH curl 1 "2007-03-03" "curl" "2007-03-03"
.SH "NAME"
curl \- transfer a URL
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& curl [options] [URL...]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
curl is a tool to transfer data from or to a server, using one of the
supported protocols (\s-1HTTP\s0, \s-1HTTPS\s0, \s-1FTP\s0, \s-1FTPS\s0, \s-1TFTP\s0, \s-1DICT\s0, \s-1TELNET\s0, \s-1LDAP\s0
or \s-1FILE\s0). The command is designed to work without user interaction.
.PP
curl offers a busload of useful tricks like proxy support, user
authentication, ftp upload, \s-1HTTP\s0 post, \s-1SSL\s0 (https:) connections,
cookies, file transfer resume and more. As you will see below, the
amount of features will make your head spin!
.PP
curl is powered by libcurl for all transfer-related features. See
\&\fI\fIlibcurl\fI\|(3)\fR for details.
.PP
\&\s-1URL\s0 The \s-1URL\s0 syntax is protocol dependent. You'll find a detailed
description in \s-1RFC\s0 3986.
.PP
You can specify multiple URLs or parts of URLs by writing part sets
within braces as in:
.PP
.Vb 1
\& http://site.{one,two,three}.com
.Ve
.PP
or you can get sequences of alphanumeric series by using [] as in:
.PP
.Vb 3
\& 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
.Ve
.PP
No nesting of the sequences is supported at the moment, but you can
use several ones next to each other:
.PP
.Vb 1
\& http://any.org/archive[1996\-1999]/vol[1\-4]/part{a,b,c}.html
.Ve
.PP
You can specify any amount of URLs on the command line. They will be
fetched in a sequential manner in the specified order.
.PP
Since curl 7.15.1 you can also specify step counter for the ranges, so
that you can get every Nth number or letter:
.PP
.Vb 2
\& http://www.numericals.com/file[1\-100:10].txt
\& http://www.letters.com/file[a\-z:2].txt
.Ve
.PP
If you specify \s-1URL\s0 without \fIprotocol://\fR prefix, curl will attempt to
guess what protocol you might want. It will then default to \s-1HTTP\s0 but
try other protocols based on often-used host name prefixes. For
example, for host names starting with \*(L"ftp.\*(R" curl will assume you want
to speak \s-1FTP\s0.
.PP
Curl will attempt to re-use connections for multiple file transfers,
so that getting many files from the same server will not do multiple
connects / handshakes. This improves speed. Of course this is only
done on files specified on a single command line and cannot be used
between separate curl invokes.
.Sh "\s-1PROGRESS\s0 \s-1METER\s0"
.IX Subsection "PROGRESS METER"
curl normally displays a progress meter during operations, indicating
amount of transfered data, transfer speeds and estimated time left
etc.
.PP
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.
.PP
If you want a progress meter for \s-1HTTP\s0 \s-1POST\s0 or \s-1PUT\s0 requests, you need
to redirect the response output to a file, using shell redirect (>),
\&\fB\-o [file]\fR or similar.
.PP
It is not the same case for \s-1FTP\s0 upload as that operation is not
spitting out any response data to the terminal.
.PP
If you prefer a progress \*(L"bar\*(R" instead of the regular meter, \fB\-#\fR is
your friend.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-a|\-\-append\fR" 4
.IX Item "-a|--append"
(\s-1FTP\s0) When used in an \s-1FTP\s0 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.
.Sp
If this option is used twice, the second one will disable append mode
again.
.ie n .IP "\fB\-A|\-\-user\-agent ""agent string""\fR" 4
.el .IP "\fB\-A|\-\-user\-agent ``agent string''\fR" 4
.IX Item "-A|--user-agent agent string"
(\s-1HTTP\s0) Specify the User-Agent string to send to the \s-1HTTP\s0 server. Some
badly done CGIs fail if its not set to \*(L"Mozilla/4.0\*(R". To encode blanks
in the string, surround the string with single quote marks. This can
also be set with the \fB\-H/\-\-header\fR option of course.
.Sp
If this option is set more than once, the last one will be the one
that's used.
.IP "\fB\-\-anyauth\fR" 4
.IX Item "--anyauth"
(\s-1HTTP\s0) 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 \-\-basic,
\&\-\-digest, \-\-ntlm, and \-\-negotiate.
.Sp
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.
.Sp
If this option is used several times, the following occurrences make no difference.
.IP "\fB\-b/\-\-cookie name=data\fR" 4
.IX Item "-b/--cookie name=data"
(\s-1HTTP\s0) Pass the data to the \s-1HTTP\s0 server as a cookie. It is supposedly
the data previously received from the server in a \*(L"Set\-Cookie:\*(R" line.
The data should be in the format \*(L"NAME1=VALUE1; NAME2=VALUE2\*(R".
.Sp
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
\&\*(L"cookie parser\*(R" 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 \s-1HTTP\s0 headers or the Netscape/Mozilla cookie file
format.
.Sp
\&\s-1NOTE\s0 that the file specified with \-b/\-\-cookie is only used as input.
No cookies will be stored in the file. To store cookies, use the
\&\-c/\-\-cookie\-jar option or you could even save the \s-1HTTP\s0 headers to a
file using \-D/\-\-dump\-header!
.Sp
If this option is set more than once, the last one will be the one that's used.
.IP "\fB\-B/\-\-use\-ascii\fR" 4
.IX Item "-B/--use-ascii"
Enable \s-1ASCII\s0 transfer when using \s-1FTP\s0 or \s-1LDAP\s0. For \s-1FTP\s0, this can also
be enforced by using an \s-1URL\s0 that ends with \*(L";type=A\*(R". This option
causes data sent to stdout to be in text mode for win32 systems.
.Sp
If this option is used twice, the second one will disable \s-1ASCII\s0 usage.
.IP "\fB\-\-basic\fR" 4
.IX Item "--basic"
(\s-1HTTP\s0) Tells curl to use \s-1HTTP\s0 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 \-\-ntlm, \-\-digest and \-\-negotiate).
.Sp
If this option is used several times, the following occurrences make
no difference.
.IP "\fB\-\-ciphers " 4
.IX Item "--ciphers "
(\s-1SSL\s0) Specifies which ciphers to use in the connection. The list of
ciphers must be using valid ciphers. Read up on \s-1SSL\s0 cipher list
details on this \s-1URL:\s0 http://www.openssl.org/docs/apps/ciphers.html
.Sp
If this option is used several times, the last one will override the
others.
.IP "\fB\-\-compressed\fR" 4
.IX Item "--compressed"
(\s-1HTTP\s0) 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.
.Sp
If this option is used several times, each occurrence will toggle it on/off.
.IP "\fB\-\-connect\-timeout seconds\fR" 4
.IX Item "--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 \-m/\-\-max\-time option.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-c/\-\-cookie\-jar file\fR" 4
.IX Item "-c/--cookie-jar file"
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, \*(L"\-\*(R", the cookies will be written to stdout.
.Sp
\&\s-1NOTE\s0 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.
.Sp
If this option is used several times, the last specified file name
will be used.
.IP "\fB\-C/\-\-continue\-at offset\fR" 4
.IX Item "-C/--continue-at offset"
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 \s-1SIZE\s0 will
not be used by curl.
.Sp
Use \*(L"\-C \-\*(R" to tell curl to automatically find out where/how to resume
the transfer. It then uses the given out\- put/input files to figure
that out.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-\-create\-dirs\fR" 4
.IX Item "--create-dirs"
When used in conjunction with the \-o option, curl will create the
necessary local directory hierarchy as needed. This option creates the
dirs mentioned with the \-o option, nothing else. If the \-o file name
uses no dir or if the dirs it mentions already exist, no dir will be
created.
.Sp
To create remote directories when using \s-1FTP\s0, try \-\-ftp\-create\-dirs.
.IP "\fB\-\-crlf \fR" 4
.IX Item "--crlf "
(\s-1FTP\s0) Convert \s-1LF\s0 to \s-1CRLF\s0 in upload. Useful for \s-1MVS\s0 (\s-1OS/390\s0).
.Sp
If this option is used several times, the following occurrences make
no difference.
.IP "\fB\-d/\-\-data data\fR" 4
.IX Item "-d/--data data"
(\s-1HTTP\s0) Sends the specified data in a \s-1POST\s0 request to the \s-1HTTP\s0 server,
in a way that can emulate as if a user has filled in a \s-1HTML\s0 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 \*(L"url\-encoded\*(R". This will cause curl to pass the
data to the server using the content-type
application/x\-www\-form\-urlencoded. Compare to \-F/\-\-form. If this
option 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'.
.Sp
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 \f(CW@foobar\fR".
.Sp
To post data purely binary, you should instead use the \-\-data\-binary
option.
.Sp
If this option is used several times, the ones following the first
will append data.
.IP "\fB\-\-data\-ascii data\fR" 4
.IX Item "--data-ascii data"
(\s-1HTTP\s0) This is an alias for the \-d/\-\-data option.
.Sp
If this option is used several times, the ones following the first will append data.
.IP "\fB\-\-data\-binary data\fR" 4
.IX Item "--data-binary data"
(\s-1HTTP\s0) 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.
.Sp
If this option is used several times, the ones following the first
will append data.
.IP "\fB\-\-digest\fR" 4
.IX Item "--digest"
(\s-1HTTP\s0) Enables \s-1HTTP\s0 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 \-u/\-\-user option to set
user name and password. See also \-\-ntlm, \-\-negotiate and \-\-anyauth for
related options.
.Sp
If this option is used several times, the following occurrences make
no difference.
.IP "\fB\-\-disable\-eprt\fR" 4
.IX Item "--disable-eprt"
(\s-1FTP\s0) Tell curl to disable the use of the \s-1EPRT\s0 and \s-1LPRT\s0 commands when
doing active \s-1FTP\s0 transfers. Curl will normally always first attempt to
use \s-1EPRT\s0, then \s-1LPRT\s0 before using \s-1PORT\s0, but with this option, it will
use \s-1PORT\s0 right away. \s-1EPRT\s0 and \s-1LPRT\s0 are extensions to the original \s-1FTP\s0
protocol, may not work on all servers but enable more functionality in
a better way than the traditional \s-1PORT\s0 command.
.Sp
If this option is used several times, each occurrence will toggle this on/off.
.IP "\fB\-\-disable\-epsv\fR" 4
.IX Item "--disable-epsv"
(\s-1FTP\s0) Tell curl to disable the use of the \s-1EPSV\s0 command when doing
passive \s-1FTP\s0 transfers. Curl will normally always first attempt to use
\&\s-1EPSV\s0 before \s-1PASV\s0, but with this option, it will not try using \s-1EPSV\s0.
.Sp
If this option is used several times, each occurrence will toggle this
on/off.
.IP "\fB\-D/\-\-dump\-header file\fR" 4
.IX Item "-D/--dump-header file"
Write the protocol headers to the specified file.
.Sp
This option is handy to use when you want to store the headers that a
\&\s-1HTTP\s0 site sends to you. Cookies from the headers could then be read in
a second curl invoke by using the \-b/\-\-cookie option! The
\&\-c/\-\-cookie\-jar option is however a better way to store cookies.
.Sp
When used on \s-1FTP\s0, the ftp server response lines are considered being
\&\*(L"headers\*(R" and thus are saved there.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-e/\-\-referer \s-1URL\s0\fR" 4
.IX Item "-e/--referer URL"
(\s-1HTTP\s0) Sends the \*(L"Referer Page\*(R" information to the \s-1HTTP\s0 server. This
can also be set with the \-H/\-\-header flag of course. When used with
\&\-L/\-\-location you can append \*(L";auto\*(R" to the \-\-referer \s-1URL\s0 to make curl
automatically set the previous \s-1URL\s0 when it follows a Location: header.
The \*(L";auto\*(R" string can be used alone, even if you don't set an initial
\&\-\-referer.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-\-engine name\fR" 4
.IX Item "--engine name"
Select the OpenSSL crypto engine to use for cipher operations. Use
\&\-\-engine list to print a list of build-time supported engines. Note
that not all (or none) of the engines may be available at run\-time.
.IP "\fB\-\-environment\fR" 4
.IX Item "--environment"
(\s-1RISC\s0 \s-1OS\s0 \s-1ONLY\s0) Sets a range of environment variables, using the names
the \-w option supports, to easier allow extraction of useful
information after having run curl.
.Sp
If this option is used several times, each occurrence will toggle this
on/off.
.IP "\fB\-\-egd\-file file\fR" 4
.IX Item "--egd-file file"
(\s-1HTTPS\s0) Specify the path name to the Entropy Gathering Daemon socket.
The socket is used to seed the random engine for \s-1SSL\s0 connections. See
also the \-\-random\-file option.
.IP "\fB\-E/\-\-cert certificate[:password]\fR" 4
.IX Item "-E/--cert certificate[:password]"
(\s-1HTTPS\s0) Tells curl to use the specified certificate file when getting
a file with \s-1HTTPS\s0. The certificate must be in \s-1PEM\s0 format. If the
optional password isn't specified, it will be queried for on the
terminal. Note that this certificate is the private key and the
private certificate concatenated!
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-\-cert\-type type\fR" 4
.IX Item "--cert-type type"
(\s-1SSL\s0) Tells curl what certificate type the provided certificate is in.
\&\s-1PEM\s0, \s-1DER\s0 and \s-1ENG\s0 are recognized types.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-\-cacert CA-certificate\fR" 4
.IX Item "--cacert CA-certificate"
(\s-1HTTPS\s0) Tells curl to use the specified certificate file to verify the
peer. The file may contain multiple \s-1CA\s0 certificates. The
certificate(s) must be in \s-1PEM\s0 format.
.Sp
curl recognizes the environment variable named '\s-1CURL_CA_BUNDLE\s0' if
that is set, and uses the given path as a path to a \s-1CA\s0 cert bundle.
This option overrides that variable.
.Sp
The windows version of curl will automatically look for a \s-1CA\s0 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 \s-1PATH\s0.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-\-capath " 4
.IX Item "--capath "
(\s-1HTTPS\s0) Tells curl to use the specified certificate directory to
verify the peer. The certificates must be in \s-1PEM\s0 format, and the
directory must have been processed using the c_rehash utility supplied
with openssl. Using \-\-capath can allow curl to make https connections
much more efficiently than using \-\-cacert if the \-\-cacert file
contains many \s-1CA\s0 certificates.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-f/\-\-fail\fR" 4
.IX Item "-f/--fail"
(\s-1HTTP\s0) 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 \s-1HTTP\s0 server fails to deliver a
docu\- ment, it returns an \s-1HTML\s0 document stating so (which often also
describes why and more). This flag will prevent curl from outputting
that and return error 22.
.Sp
If this option is used twice, the second will again disable silent failure.
.IP "\fB\-\-ftp\-account [data]\fR" 4
.IX Item "--ftp-account [data]"
(\s-1FTP\s0) When an \s-1FTP\s0 server asks for \*(L"account data\*(R" after user name and
password has been provided, this data is sent off using the \s-1ACCT\s0
command. (Added in 7.13.0)
.Sp
If this option is used twice, the second will override the previous use.
.IP "\fB\-\-ftp\-create\-dirs\fR" 4
.IX Item "--ftp-create-dirs"
(\s-1FTP\s0) When an \s-1FTP\s0 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.
.Sp
If this option is used twice, the second will again disable directory creation.
.IP "\fB\-\-ftp\-method [method]\fR" 4
.IX Item "--ftp-method [method]"
(\s-1FTP\s0) Control what method curl should use to reach a file on a \s-1FTP\s0(S)
server. The method argument should be one of the following
alternatives:
.RS 4
.IP "multicwd" 4
.IX Item "multicwd"
curl does a single \s-1CWD\s0 operation for each path part in the given \s-1URL\s0.
For deep hierarchies this means very many commands. This is how
\&\s-1RFC1738\s0 says it should be done. This is the default but the slowest
behavior.
.IP "nocwd" 4
.IX Item "nocwd"
curl does no \s-1CWD\s0 at all. curl will do \s-1SIZE\s0, \s-1RETR\s0, \s-1STOR\s0 etc and give a
full path to the server for all these commands. This is the fastest
behavior.
.IP "singlecwd" 4
.IX Item "singlecwd"
curl does one \s-1CWD\s0 with the full target directory and then operates on
the file \*(L"normally\*(R" (like in the multicwd case). This is somewhat more
standards compliant than 'nocwd' but without the full penalty
\&'multicwd'.
.RE
.RS 4
.RE
.IP "\fB\-\-ftp\-pasv\fR" 4
.IX Item "--ftp-pasv"
(\s-1FTP\s0) Use \s-1PASV\s0 when transferring. \s-1PASV\s0 is the internal default
behavior, but using this option can be used to override a previous
\&\-\-ftp\-port option. (Added in 7.11.0)
.Sp
If this option is used several times, the following occurrences make
no difference.
.IP "\fB\-\-ftp\-alternative\-to\-user command\fR" 4
.IX Item "--ftp-alternative-to-user command"
(\s-1FTP\s0) If authenticating with the \s-1USER\s0 and \s-1PASS\s0 commands fails, send
this command. When connecting to Tumble\- weed's Secure Transport
server over \s-1FTPS\s0 using a client certificate, using \*(L"\s-1SITE\s0 \s-1AUTH\s0\*(R" will
tell the server to retrieve the username from the certificate. (Added
in 7.15.5)
.IP "\fB\-\-ftp\-skip\-pasv\-ip\fR" 4
.IX Item "--ftp-skip-pasv-ip"
(\s-1FTP\s0) Tell curl to not use the \s-1IP\s0 address the server suggests in its
response to curl's \s-1PASV\s0 command when curl connects the data
connection. Instead curl will re-use the same \s-1IP\s0 address it already
uses for the control con\- nection. (Added in 7.14.2)
.Sp
This option has no effect if \s-1PORT\s0, \s-1EPRT\s0 or \s-1EPSV\s0 is used instead of
\&\s-1PASV\s0.
.Sp
If this option is used twice, the second will again use the server's
suggested address.
.IP "\fB\-\-ftp\-ssl\fR" 4
.IX Item "--ftp-ssl"
(\s-1FTP\s0) Try to use \s-1SSL/TLS\s0 for the \s-1FTP\s0 connection. Reverts to a
non-secure connection if the server doesn't sup\- port \s-1SSL/TLS\s0. (Added
in 7.11.0)
.Sp
If this option is used twice, the second will again disable this.
.IP "\fB\-\-ftp\-ssl\-reqd\fR" 4
.IX Item "--ftp-ssl-reqd"
(\s-1FTP\s0) Require \s-1SSL/TLS\s0 for the \s-1FTP\s0 connection. Terminates the
connection if the server doesn't support \s-1SSL/TLS\s0. (Added in 7.15.5)
.Sp
If this option is used twice, the second will again disable this.
.IP "\fB\-F/\-\-form name=content\fR" 4
.IX Item "-F/--form name=content"
(\s-1HTTP\s0) This lets curl emulate a filled in form in which a user has
pressed the submit button. This causes curl to \s-1POST\s0 data using the
Content-Type multipart/form\-data according to \s-1RFC1867\s0. 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 con\- tent
part from a file, prefix the file name with the letter " 4
.IX Item "--key-type type>"
(\s-1SSL\s0) Private key file type. Specify which type your \-\-key provided
private key is. \s-1DER\s0, \s-1PEM\s0 and \s-1ENG\s0 are sup\- ported.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-\-krb4 level\fR" 4
.IX Item "--krb4 level"
(\s-1FTP\s0) Enable kerberos4 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.
.Sp
This option requires that the library was built with kerberos4
support. This is not very common. Use \-V/\-\-ver\- sion to see if your
curl supports it.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-K/\-\-config file\fR" 4
.IX Item "-K/--config file"
Specify which config file to read curl arguments from. The config file
is a text file in which command line arguments can be written which
then will be used as if they were written on the actual command line.
Options and their parameters must be specified on the same config file
line. If the parameter is to contain white spaces, the parameter must
be enclosed within quotes. If the first column of a config line is a
\&'#' character, the rest of the line will be treated as a comment.
.Sp
Specify the filename as '\-' to make curl read the file from stdin.
.Sp
Note that to be able to specify a \s-1URL\s0 in the config file, you need to
specify it using the \-\-url option, and not by simply writing the \s-1URL\s0
on its own line. So, it could look similar to this:
.Sp
.Vb 1
\& url = "http://curl.haxx.se/docs/"
.Ve
.Sp
This option can be used multiple times.
.Sp
When curl is invoked, it always (unless \-q 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:
.RS 4
.IP "*" 4
curl tries to find the \*(L"home dir\*(R": It first checks for the \s-1CURL_HOME\s0
and then the \s-1HOME\s0 environment vari\- ables. Failing that, it uses
\&\fIgetpwuid()\fR on unix-like systems (which returns the home dir given the
current user in your system). On Windows, it then checks for the
\&\s-1APPDATA\s0 variable, or as a last resort the '%USERPRO\-FILE%0lication
Data'.
.IP "*" 4
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.
.RE
.RS 4
.RE
.IP "\fB\-\-limit\-rate speed\fR" 4
.IX Item "--limit-rate speed"
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.
.Sp
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.
.Sp
If you are also using the \-Y/\-\-speed\-limit option, that option will
take precedence and might cripple the rate\- limiting slightly, to help
keeping the speed-limit logic working.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-l/\-\-list\-only\fR" 4
.IX Item "-l/--list-only"
(\s-1FTP\s0) When listing an \s-1FTP\s0 directory, this switch forces a name-only
view. Especially useful if you want to machine-parse the contents of
an \s-1FTP\s0 directory since the normal directory view doesn't use a
standard look or format.
.Sp
This option causes an \s-1FTP\s0 \s-1NLST\s0 command to be sent. Some \s-1FTP\s0 servers
list only files in their response to \s-1NLST\s0; they do not include
subdirectories and symbolic links.
.Sp
If this option is used twice, the second will again disable list only.
.IP "\fB\-\-local\-port num[\-num]\fR" 4
.IX Item "--local-port num[-num]"
Set a prefered number or range of local port numbers to use for the
connection(s). Note that port numbers by nature is a scarce resource
that will be busy at times so setting this range to something too
narrow might cause unnecessary connection setup failures. (Added in
7.15.2)
.IP "\fB\-L/\-\-location\fR" 4
.IX Item "-L/--location"
(\s-1HTTP/HTTPS\s0) 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 \-i/\-\-include or \-I/\-\-head, 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 \-\-location\-trusted on how to change this. You
can limit the amount of redirects to follow by using the \-\-max\-redirs
option.
.Sp
If this option is used twice, the second will again disable location
following.
.IP "\fB\-\-location\-trusted\fR" 4
.IX Item "--location-trusted"
(\s-1HTTP/HTTPS\s0) Like \-L/\-\-location, 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 \s-1HTTP\s0 Basic authentication).
.Sp
If this option is used twice, the second will again disable location
following.
.IP "\fB\-\-max\-filesize bytes\fR" 4
.IX Item "--max-filesize bytes"
Specify the maximum size (in bytes) of a file to download. If the file
requested is larger than this value, the transfer will not start and
curl will return with exit code 63.
.Sp
\&\s-1NOTE:\s0 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 \s-1FTP\s0 and \s-1HTTP\s0
transfers.
.IP "\fB\-m/\-\-max\-time seconds\fR" 4
.IX Item "-m/--max-time seconds"
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
\&\-\-connect\-timeout option.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-M/\-\-manual\fR" 4
.IX Item "-M/--manual"
Manual. Display the huge help text.
.IP "\fB\-n/\-\-netrc\fR" 4
.IX Item "-n/--netrc"
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 \fInetrc\fR\|(4) or
\&\fIftp\fR\|(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 \*(L"\s-1HOME\s0\*(R" is used to find the home
directory.
.Sp
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:
.Sp
.Vb 1
\& machine host.domain.com login myself password secret
.Ve
.Sp
If this option is used twice, the second will again disable netrc
usage.
.IP "\fB\-\-netrc\-optional\fR" 4
.IX Item "--netrc-optional"
Very similar to \-\-netrc, but this option makes the .netrc usage
optional and not mandatory as the \-\-netrc does.
.IP "\fB\-\-negotiate\fR" 4
.IX Item "--negotiate"
(\s-1HTTP\s0) 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 \s-1IETF\s0 draft draft\-brezak\-spnego\-http\-04.txt.
.Sp
This option requires that the library was built with \s-1GSSAPI\s0 support.
This is not very common. Use \-V/\-\-version to see if your version
supports GSS\-Negotiate.
.Sp
When using this option, you must also provide a fake \-u/\-\-user option
to activate the authentication code prop\- erly. Sending a '\-u :' is
enough as the user name and password from the \-u option aren't
actually used.
.Sp
If this option is used several times, the following occurrences make
no difference.
.IP "\fB\-N/\-\-no\-buffer\fR" 4
.IX Item "-N/--no-buffer"
Disables the buffering of the output stream. In normal work
situations, curl will use a standard buffered out\- put 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.
.Sp
If this option is used twice, the second will again switch on buffering.
.IP "\fB\-\-ntlm\fR" 4
.IX Item "--ntlm"
(\s-1HTTP\s0) Enables \s-1NTLM\s0 authentication. The \s-1NTLM\s0 authentication method was
designed by Microsoft and is used by \s-1IIS\s0
.Sp
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 \s-1NTLM\s0 to switch to a public and documented authentication
method instead. Such as Digest.
.Sp
If you want to enable \s-1NTLM\s0 for your proxy authentication, then use
\&\-\-proxy\-ntlm.
.Sp
This option requires that the library was built with \s-1SSL\s0 support. Use
\&\-V/\-\-version to see if your curl supports \s-1NTLM\s0.
.Sp
If this option is used several times, the following occurrences make
no difference.
.IP "\fB\-o/\-\-output file\fR" 4
.IX Item "-o/--output file"
Write output to instead of stdout. If you are using {} or [] to
fetch multiple documents, you can use '#' followed by a number in the
specifier. That variable will be replaced with the current
string for the \s-1URL\s0 being fetched. Like in:
.Sp
.Vb 1
\& curl http://{one,two}.site.com \-o "file_#1.txt"
.Ve
.Sp
or use several variables like:
.Sp
.Vb 1
\& curl http://{site,host}.host[1\-5].com \-o "#1_#2"
.Ve
.Sp
You may use this option as many times as you have number of URLs.
.Sp
See also the \-\-create\-dirs option to create the local directories
dynamically.
.IP "\fB\-O/\-\-remote\-name\fR" 4
.IX Item "-O/--remote-name"
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.)
.Sp
The remote file name to use for saving is extracted from the given
\&\s-1URL\s0, nothing else.
.Sp
You may use this option as many times as you have number of URLs.
.IP "\fB\-\-pass phrase\fR" 4
.IX Item "--pass phrase"
(\s-1SSL\s0) Pass phrase for the private key
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-\-proxy\-anyauth\fR" 4
.IX Item "--proxy-anyauth"
Tells curl to pick a suitable authentication method when communicating
with the given proxy. This will cause an extra request/response
round\-trip. (Added in 7.13.2)
.Sp
If this option is used twice, the second will again disable the proxy
use-any authentication.
.IP "\fB\-\-proxy\-basic\fR" 4
.IX Item "--proxy-basic"
Tells curl to use \s-1HTTP\s0 Basic authentication when communicating with
the given proxy. Use \-\-basic for enabling \s-1HTTP\s0 Basic with a remote
host. Basic is the default authentication method curl uses with
proxies.
.Sp
If this option is used twice, the second will again disable proxy \s-1HTTP\s0
Basic authentication.
.IP "\fB\-\-proxy\-digest\fR" 4
.IX Item "--proxy-digest"
Tells curl to use \s-1HTTP\s0 Digest authentication when communicating with
the given proxy. Use \-\-digest for enabling \s-1HTTP\s0 Digest with a remote
host.
.Sp
If this option is used twice, the second will again disable proxy \s-1HTTP\s0 Digest.
.IP "\fB\-\-proxy\-ntlm\fR" 4
.IX Item "--proxy-ntlm"
Tells curl to use \s-1HTTP\s0 \s-1NTLM\s0 authentication when communicating with the
given proxy. Use \-\-ntlm for enabling \s-1NTLM\s0 with a remote host.
.Sp
If this option is used twice, the second will again disable proxy \s-1HTTP\s0 \s-1NTLM\s0.
.IP "\fB\-p/\-\-proxytunnel\fR" 4
.IX Item "-p/--proxytunnel"
When an \s-1HTTP\s0 proxy is used (\-x/\-\-proxy), 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 \s-1HTTP\s0 proxy \s-1CONNECT\s0 request and requires that the proxy
allows direct connect to the remote port number curl wants to tunnel
through to.
.Sp
If this option is used twice, the second will again disable proxy tunnel.
.IP "\fB\-P/\-\-ftp\-port address\fR" 4
.IX Item "-P/--ftp-port address"
(\s-1FTP\s0) Reverses the initiator/listener roles when connecting with ftp.
This switch makes Curl use the \s-1PORT\s0 com\- mand instead of \s-1PASV\s0. In
practice, \s-1PORT\s0 tells the server to connect to the client's specified
address and port, while \s-1PASV\s0 asks the server for an ip address and
port to connect to. should be one of:
.RS 4
.IP "interface" 4
.IX Item "interface"
i.e \*(L"eth0\*(R" to specify which interface's \s-1IP\s0 address you want to use (Unix only)
.IP "\s-1IP\s0 address" 4
.IX Item "IP address"
i.e \*(L"192.168.10.1\*(R" to specify exact \s-1IP\s0 number
.IP "host name" 4
.IX Item "host name"
i.e \*(L"my.host.domain\*(R" to specify machine
.IP "\-" 4
make curl pick the same \s-1IP\s0 address that is already used for the
control connection
.RE
.RS 4
.Sp
If this option is used several times, the last one will be used.
Disable the use of \s-1PORT\s0 with \-\-ftp\-pasv. Disable the attempt to use
the \s-1EPRT\s0 command instead of \s-1PORT\s0 by using \-\-disable\-eprt. \s-1EPRT\s0 is
really \s-1PORT++\s0.
.RE
.IP "\fB\-q\fR" 4
.IX Item "-q"
If used as the first parameter on the command line, the curlrc config
file will not be read and used. See the \-K/\-\-config for details on the
default config file search path.
.IP "\fB\-Q/\-\-quote command\fR" 4
.IX Item "-Q/--quote command"
(\s-1FTP\s0) Send an arbitrary command to the remote \s-1FTP\s0 server. Quote
commands are sent \s-1BEFORE\s0 the transfer is taking place (just after the
initial \s-1PWD\s0 command to be exact). To make commands take place after a
successful trans\- fer, 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 '+'. You may specify any
amount of commands. If the server returns failure for one of the
commands, the entire operation will be aborted. You must send
syntacti\- cally correct \s-1FTP\s0 commands as \s-1RFC959\s0 defines.
.Sp
This option can be used multiple times.
.IP "\fB\-\-random\-file file\fR" 4
.IX Item "--random-file file"
(\s-1HTTPS\s0) Specify the path name to file containing what will be
considered as random data. The data is used to seed the random engine
for \s-1SSL\s0 connections. See also the \-\-egd\-file option.
.IP "\fB\-r/\-\-range range\fR" 4
.IX Item "-r/--range range"
(\s-1HTTP/FTP\s0) Retrieve a byte range (i.e a partial document) from a
\&\s-1HTTP/1\s0.1 or \s-1FTP\s0 server. Ranges can be speci\- fied in a number of ways.
.RS 4
.IP "value 0\-499" 4
.IX Item "value 0-499"
specifies the first 500 bytes
.IP "value 500\-999" 4
.IX Item "value 500-999"
specifies the second 500 bytes
.IP "value\-500" 4
.IX Item "value-500"
specifies the last 500 bytes
.IP "value 9500\-" 4
.IX Item "value 9500-"
specifies the bytes from offset 9500 and forward
.IP "value 0\-0,\-1" 4
.IX Item "value 0-0,-1"
specifies the first and last byte only(*)(H)
.IP "value 500\-700,600\-799" 4
.IX Item "value 500-700,600-799"
specifies 300 bytes from offset 500(H)
.IP "value 100\-199,500\-599" 4
.IX Item "value 100-199,500-599"
specifies two separate 100 bytes ranges(*)(H)
.RE
.RS 4
.Sp
(*) = \s-1NOTE\s0 that this will cause the server to reply with a multipart
response!a
.Sp
You should also be aware that many \s-1HTTP/1\s0.1 servers do not have this
feature enabled, so that when you attempt to get a range, you'll
instead get the whole document.
.Sp
\&\s-1FTP\s0 range downloads only support the simple syntax 'start\-stop'
(optionally with one of the numbers omitted). It depends on the
non-RFC command \s-1SIZE\s0.
.Sp
If this option is used several times, the last one will be used.
.RE
.IP "\fB\-R/\-\-remote\-time\fR" 4
.IX Item "-R/--remote-time"
When used, this will make libcurl attempt to figure out the timestamp
of the remote file, and if that is avail\- able make the local file get
that same timestamp.
.Sp
If this option is used twice, the second time disables this again.
.IP "\fB\-\-retry num\fR" 4
.IX Item "--retry num"
If a transient error is returned when curl tries to perform a
transfer, it will retry this number of times before giving up. Setting
the number to 0 makes curl do no retries (which is the default).
Transient error means either: a timeout, an \s-1FTP\s0 5xx response code or
an \s-1HTTP\s0 5xx response code.
.Sp
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 \-\-retry\-delay you disable this
exponential backoff algorithm. See also \-\-retry\-max\-time to limit the
total time allowed for retries. (Added in 7.12.3)
.Sp
If this option is used multiple times, the last occurrence decide the
amount.
.IP "\fB\-\-retry\-delay seconds\fR" 4
.IX Item "--retry-delay seconds"
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 \-\-retry
is also used. Setting this delay to zero will make curl use the
default backoff time. (Added in 7.12.3)
.Sp
If this option is used multiple times, the last occurrence decide the
amount.
.IP "\fB\-\-retry\-max\-time seconds\fR" 4
.IX Item "--retry-max-time seconds"
The retry timer is reset before the first transfer attempt. Retries
will be done as usual (see \-\-retry) 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 \-m/\-\-max\-time. Set this option to zero to not
timeout retries. (Added in 7.12.3)
.Sp
If this option is used multiple times, the last occurrence decide the
amount.
.IP "\fB\-s/\-\-silent\fR" 4
.IX Item "-s/--silent"
Silent mode. Don't show progress meter or error messages. Makes Curl
mute.
.Sp
If this option is used twice, the second will again disable silent
mode.
.IP "\fB\-S/\-\-show\-error\fR" 4
.IX Item "-S/--show-error"
When used with \-s it makes curl show error message if it fails.
.Sp
If this option is used twice, the second will again disable show
error.
.IP "\fB\-\-socks4 host[:port]\fR" 4
.IX Item "--socks4 host[:port]"
Use the specified \s-1SOCKS4\s0 proxy. If the port number is not specified,
it is assumed at port 1080. (Added in 7.15.2)
.Sp
This option overrides any previous use of \-x/\-\-proxy, as they are
mutually exclusive.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-\-socks5 host[:port]\fR" 4
.IX Item "--socks5 host[:port]"
Use the specified \s-1SOCKS5\s0 proxy. If the port number is not specified,
it is assumed at port 1080. (Added in 7.11.1)
.Sp
This option overrides any previous use of \-x/\-\-proxy, as they are
mutually exclusive.
.Sp
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.)
.IP "\fB\-\-stderr file\fR" 4
.IX Item "--stderr file"
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.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-\-tcp\-nodelay\fR" 4
.IX Item "--tcp-nodelay"
Turn on the \s-1TCP_NODELAY\s0 option. See the \fIcurl_easy_setopt\fR\|(3) man page
for details about this option. (Added in 7.11.2)
.Sp
If this option is used several times, each occurrence toggles this
on/off.
.IP "\fB\-t/\-\-telnet\-option OPT=val\fR" 4
.IX Item "-t/--telnet-option OPT=val"
Pass options to the telnet protocol. Supported options are:
.Sp
.Vb 3
\& TTYPE= Sets the terminal type.
\& XDISPLOC= Sets the X display location.
\& NEW_ENV= Sets an environment variable.
.Ve
.IP "\fB\-T/\-\-upload\-file file\fR" 4
.IX Item "-T/--upload-file file"
This transfers the specified local file to the remote \s-1URL\s0. If there is
no file part in the specified \s-1URL\s0, Curl will append the local file
name. \s-1NOTE\s0 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 \s-1PUT\s0 command will be used.
.Sp
Use the file name \*(L"\-\*(R" (a single dash) to use stdin instead of a given
file.
.Sp
You can specify one \-T for each \s-1URL\s0 on the command line. Each \-T + \s-1URL\s0
pair specifies what to upload and to where. curl also supports
\&\*(L"globbing\*(R" of the \-T argument, meaning that you can upload multiple
files to a single \s-1URL\s0 by using the same \s-1URL\s0 globbing style supported
in the \s-1URL\s0, like this:
.Sp
.Vb 1
\& curl \-T "{file1,file2}" http://www.uploadtothissite.com
.Ve
.Sp
or even
.Sp
.Vb 1
\& curl \-T "img[1\-1000].png" ftp://ftp.picturemania.com/upload/
.Ve
.IP "\fB\-\-trace file\fR" 4
.IX Item "--trace file"
Enables a full trace dump of all incoming and outgoing data, including
descriptive information, to the given output file. Use \*(L"\-\*(R" as filename
to have the output sent to stdout.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-\-trace\-ascii file\fR" 4
.IX Item "--trace-ascii file"
Enables a full trace dump of all incoming and outgoing data, including
descriptive information, to the given output file. Use \*(L"\-\*(R" as filename
to have the output sent to stdout.
.Sp
This is very similar to \-\-trace, but leaves out the hex part and only
shows the \s-1ASCII\s0 part of the dump. It makes smaller output that might
be easier to read for untrained humans.
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-\-trace\-time\fR" 4
.IX Item "--trace-time"
Prepends a time stamp to each trace or verbose line that curl
displays. (Added in 7.14.0)
.Sp
If this option is used several times, each occurrence will toggle it on/off.
.IP "\fB\-u/\-\-user user:password\fR" 4
.IX Item "-u/--user user:password"
Specify user and password to use for server authentication. Overrides
\&\-n/\-\-netrc and \-\-netrc\-optional.
.Sp
If you use an SSPI-enabled curl binary and do \s-1NTLM\s0 autentication, you
can force curl to pick up the user name and password from your
environment by simply specifying a single colon with this option: \*(L"\-u
:\*(R".
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-U/\-\-proxy\-user user:password\fR" 4
.IX Item "-U/--proxy-user user:password"
Specify user and password to use for proxy authentication.
.Sp
If you use an SSPI-enabled curl binary and do \s-1NTLM\s0 autentication, you
can force curl to pick up the user name and password from your
environment by simply specifying a single colon with this option: \*(L"\-U
:\*(R".
.Sp
If this option is used several times, the last one will be used.
.IP "\fB\-\-url \s-1URL\s0\fR" 4
.IX Item "--url URL"
Specify a \s-1URL\s0 to fetch. This option is mostly handy when you want to
specify \s-1URL\s0(s) in a config file.
.Sp
This option may be used any number of times. To control where this \s-1URL\s0
is written, use the \-o/\-\-output or the \-O/\-\-remote\-name options.
.IP "\fB\-v/\-\-verbose\fR" 4
.IX Item "-v/--verbose"
Makes the fetching more verbose/talkative. Mostly usable for
debugging. Lines starting with '>' means \*(L"header data\*(R" sent by curl,
\&'
.Sp
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 \*(L"string\*(R",
to get read from a particular file you specify it \*(L"@filename\*(R" and to
tell curl to read the format from stdin you write \*(L"@\-\*(R".
.Sp
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 \en, a carriage
return with \er and a tab space with \et.
.Sp
\&\s-1NOTE:\s0 The %\-letter is a special letter in the win32\-environment, where
all occurrences of % must be doubled when using this option.
.Sp
Available variables are at this point:
.IP "url_effective" 4
.IX Item "url_effective"
The \s-1URL\s0 that was fetched last. This is mostly meaningful if you've
told curl to follow location: headers.
.IP "http_code" 4
.IX Item "http_code"
The numerical code that was found in the last retrieved \s-1HTTP\s0(S) page.
.IP "http_connect" 4
.IX Item "http_connect"
The numerical code that was found in the last response (from a proxy)
to a curl \s-1CONNECT\s0 request. (Added in 7.12.4)
.IP "time_total" 4
.IX Item "time_total"
The total time, in seconds, that the full operation lasted. The time
will be displayed with mil\- lisecond resolution.
.IP "time_namelookup" 4
.IX Item "time_namelookup"
The time, in seconds, it took from the start until the name resolving was completed.
.Sp
time_connect The time, in seconds, it took from the start until the
connect to the remote host (or proxy) was completed.
.IP "time_pretransfer" 4
.IX Item "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.
.IP "time_redirect" 4
.IX Item "time_redirect"
The time, in seconds, it took for all redirection steps include name
lookup, connect, pretrans\- fer and transfer before final transaction
was started. time_redirect shows the complete execu\- tion time for
multiple redirections. (Added in 7.12.3)
.IP "time_starttransfer" 4
.IX Item "time_starttransfer"
The time, in seconds, it took from the start until the first byte is
just about to be trans\- ferred. This includes time_pretransfer and
also the time the server needs to calculate the result.
.IP "size_download" 4
.IX Item "size_download"
The total amount of bytes that were downloaded.
.IP "size_upload" 4
.IX Item "size_upload"
The total amount of bytes that were uploaded.
.IP "size_header" 4
.IX Item "size_header"
The total amount of bytes of the downloaded headers.
.IP "size_request" 4
.IX Item "size_request"
The total amount of bytes that were sent in the \s-1HTTP\s0 request.
.IP "speed_download" 4
.IX Item "speed_download"
The average download speed that curl measured for the complete download.
.IP "speed_upload" 4
.IX Item "speed_upload"
The average upload speed that curl measured for the complete upload.
.IP "content_type" 4
.IX Item "content_type"
The Content-Type of the requested document, if there was any.
.IP "num_connects" 4
.IX Item "num_connects"
Number of new connects made in the recent transfer. (Added in 7.12.3)
.IP "num_redirects" 4
.IX Item "num_redirects"
Number of redirects that were followed in the request. (Added in 7.12.3)
.IP "ftp_entry_path" 4
.IX Item "ftp_entry_path"
The initial path libcurl ended up in when logging on to the remote \s-1FTP\s0
server. (Added in 7.15.4)
.RE
.RS 4
.Sp
If this option is used several times, the last one will be used.
.Sp
\&\-x/\-\-proxy
.Sp
Use specified \s-1HTTP\s0 proxy. If the port number is not specified, it is
assumed at port 1080.
.Sp
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.
.Sp
Note that all operations that are performed over a \s-1HTTP\s0 proxy will
transparently be converted to \s-1HTTP\s0. 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 \-p/\-\-proxytunnel
option.
.Sp
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.
.Sp
If this option is used several times, the last one will be used.
.Sp
\&\-X/\-\-request
.Sp
(\s-1HTTP\s0) Specifies a custom request method to use when communicating
with the \s-1HTTP\s0 server. The specified request will be used instead of
the method otherwise used (which defaults to \s-1GET\s0). Read the \s-1HTTP\s0 1.1
specification for details and explanations.
.Sp
(\s-1FTP\s0) Specifies a custom \s-1FTP\s0 command to use instead of \s-1LIST\s0 when doing
file lists with ftp.
.Sp
If this option is used several times, the last one will be used.
.Sp
\&\-y/\-\-speed\-time
.Sp
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.
.Sp
This option controls transfers and thus will not affect slow connects
etc. If this is a concern for you, try the \-\-connect\-timeout option.
.Sp
If this option is used several times, the last one will be used.
.Sp
\&\-Y/\-\-speed\-limit
.Sp
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.
.Sp
If this option is used several times, the last one will be used.
.Sp
\&\-z/\-\-time\-cond
.Sp
(\s-1HTTP\s0) 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 \fIcurl_getdate\fR\|(3) man pages for date expression
details.
.Sp
Start the date expression with a dash (\-) to make it request for a
document that is older than the given date/time, default is a document
that is newer than the specified date/time.
.Sp
If this option is used several times, the last one will be used.
.Sp
\&\-\-max\-redirs
.Sp
Set maximum number of redirection-followings allowed. If \-L/\-\-location
is used, this option can be used to pre\- vent curl from following
redirections \*(L"in absurdum\*(R". By default, the limit is set to 50
redirections. Set this option to \-1 to make it limitless.
.Sp
If this option is used several times, the last one will be used.
.Sp
\&\-0/\-\-http1.0
.Sp
(\s-1HTTP\s0) Forces curl to issue its requests using \s-1HTTP\s0 1.0 instead of
using its internally preferred: \s-1HTTP\s0 1.1.
.Sp
\&\-1/\-\-tlsv1
.Sp
(\s-1HTTPS\s0) Forces curl to use \s-1TSL\s0 version 1 when negotiating with a
remote \s-1TLS\s0 server.
.Sp
\&\-2/\-\-sslv2
.Sp
(\s-1HTTPS\s0) Forces curl to use \s-1SSL\s0 version 2 when negotiating with a
remote \s-1SSL\s0 server.
.Sp
\&\-3/\-\-sslv3
.Sp
(\s-1HTTPS\s0) Forces curl to use \s-1SSL\s0 version 3 when negotiating with a
remote \s-1SSL\s0 server.
.Sp
\&\-\-3p\-quote
.Sp
(\s-1FTP\s0) Specify arbitrary commands to send to the source server. See the
\&\-Q/\-\-quote option for details. (Added in 7.13.0)
.Sp
\&\-\-3p\-url
.Sp
(\s-1FTP\s0) Activates a \s-1FTP\s0 3rd party transfer. Specifies the source \s-1URL\s0 to
get a file from, while the \*(L"normal\*(R" \s-1URL\s0 will be used as target \s-1URL\s0,
the file that will be written/created.
.Sp
Note that not all \s-1FTP\s0 server allow 3rd party transfers. (Added in 7.13.0)
.Sp
\&\-\-3p\-user
.Sp
(\s-1FTP\s0) Specify user:password for the source \s-1URL\s0 transfer. (Added in
7.13.0)
.Sp
\&\-4/\-\-ipv4
.Sp
If libcurl is capable of resolving an address to multiple \s-1IP\s0 versions
(which it is if it is ipv6\-capable), this option tells libcurl to
resolve names to IPv4 addresses only.
.Sp
\&\-6/\-\-ipv6
.Sp
If libcurl is capable of resolving an address to multiple \s-1IP\s0 versions
(which it is if it is ipv6\-capable), this option tells libcurl to
resolve names to IPv6 addresses only.
.Sp
\&\-#/\-\-progress\-bar
.Sp
Make curl display progress information as a progress bar instead of
the default statistics.
.Sp
If this option is used twice, the second will again disable the
progress bar.
.RE
.SH "FILES"
.IX Header "FILES"
.IP "\fB~/.curlrc\fR" 4
.IX Item "~/.curlrc"
Default config file, see \fB\-K/\-\-config\fR for details.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "http_proxy [protocol://][:port]" 4
.IX Item "http_proxy [protocol://][:port]"
Sets proxy server to use for \s-1HTTP\s0.
.IP "\s-1HTTPS_PROXY\s0 [protocol://][:port]" 4
.IX Item "HTTPS_PROXY [protocol://][:port]"
Sets proxy server to use for \s-1HTTPS\s0.
.IP "\s-1FTP_PROXY\s0 [protocol://][:port]" 4
.IX Item "FTP_PROXY [protocol://][:port]"
Sets proxy server to use for \s-1FTP\s0.
.IP "\s-1ALL_PROXY\s0 [protocol://][:port]" 4
.IX Item "ALL_PROXY [protocol://][:port]"
Sets proxy server to use if no protocol-specific proxy is set.
.IP "\s-1NO_PROXY\s0 " 4
.IX Item "NO_PROXY "
list of host names that shouldn't go through any proxy. If set to a
asterisk '*' only, it matches all hosts.
.SH "EXIT CODES"
.IX Header "EXIT CODES"
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:
.IP "1" 1
.IX Item "1"
Unsupported protocol. This build of curl has no support for this
protocol.
.IP "2" 1
.IX Item "2"
Failed to initialize.
.IP "3" 1
.IX Item "3"
\&\s-1URL\s0 malformat. The syntax was not correct.
.IP "4" 1
.IX Item "4"
\&\s-1URL\s0 user malformatted. The user-part of the \s-1URL\s0 syntax was not correct.
.IP "5" 1
.IX Item "5"
Couldn't resolve proxy. The given proxy host could not be resolved.
.IP "6" 1
.IX Item "6"
Couldn't resolve host. The given remote host was not resolved.
.IP "7" 1
.IX Item "7"
Failed to connect to host.
.IP "8" 1
.IX Item "8"
\&\s-1FTP\s0 weird server reply. The server sent data curl couldn't parse.
.IP "9" 1
.IX Item "9"
\&\s-1FTP\s0 access denied. The server denied login or denied access to the
particular resource or directory you wanted to reach. Most often you
tried to change to a directory that doesn't exist on the server.
.IP "10" 1
.IX Item "10"
\&\s-1FTP\s0 user/password incorrect. Either one or both were not accepted by the server.
.IP "11" 1
.IX Item "11"
\&\s-1FTP\s0 weird \s-1PASS\s0 reply. Curl couldn't parse the reply sent to the \s-1PASS\s0 request.
.IP "12" 1
.IX Item "12"
\&\s-1FTP\s0 weird \s-1USER\s0 reply. Curl couldn't parse the reply sent to the \s-1USER\s0 request.
.IP "13" 1
.IX Item "13"
\&\s-1FTP\s0 weird \s-1PASV\s0 reply, Curl couldn't parse the reply sent to the \s-1PASV\s0 request.
.IP "14" 1
.IX Item "14"
\&\s-1FTP\s0 weird 227 format. Curl couldn't parse the 227\-line the server sent.
.IP "15" 1
.IX Item "15"
\&\s-1FTP\s0 can't get host. Couldn't resolve the host \s-1IP\s0 we got in the 227\-line.
.IP "16" 1
.IX Item "16"
\&\s-1FTP\s0 can't reconnect. Couldn't connect to the host we got in the 227\-line.
.IP "17" 1
.IX Item "17"
\&\s-1FTP\s0 couldn't set binary. Couldn't change transfer method to binary.
.IP "18" 1
.IX Item "18"
Partial file. Only a part of the file was transferred.
.IP "19" 1
.IX Item "19"
\&\s-1FTP\s0 couldn't download/access the given file, the \s-1RETR\s0 (or similar) command failed.
.IP "20" 1
.IX Item "20"
\&\s-1FTP\s0 write error. The transfer was reported bad by the server.
.IP "21" 1
.IX Item "21"
\&\s-1FTP\s0 quote error. A quote command returned error from the server.
.IP "22" 1
.IX Item "22"
\&\s-1HTTP\s0 page not retrieved. The requested url was not found or returned
another error with the \s-1HTTP\s0 error code being 400 or above. This return
code only appears if \fB\-f/\-\-fail\fR is used.
.IP "23" 1
.IX Item "23"
Write error. Curl couldn't write data to a local filesystem or similar.
.IP "24" 1
.IX Item "24"
Malformed user. User name badly specified.
.IP "25" 1
.IX Item "25"
\&\s-1FTP\s0 couldn't \s-1STOR\s0 file. The server denied the \s-1STOR\s0 operation, used for \s-1FTP\s0 uploading.
.IP "26" 1
.IX Item "26"
Read error. Various reading problems.
.IP "27" 1
.IX Item "27"
Out of memory. A memory allocation request failed.
.IP "28" 1
.IX Item "28"
Operation timeout. The specified time-out period was reached according to the conditions.
.IP "29" 1
.IX Item "29"
\&\s-1FTP\s0 couldn't set \s-1ASCII\s0. The server returned an unknown reply.
.IP "30" 1
.IX Item "30"
\&\s-1FTP\s0 \s-1PORT\s0 failed. The \s-1PORT\s0 command failed. Not all \s-1FTP\s0 servers support
the \s-1PORT\s0 command, try doing a transfer using \s-1PASV\s0 instead!
.IP "31" 1
.IX Item "31"
\&\s-1FTP\s0 couldn't use \s-1REST\s0. The \s-1REST\s0 command failed. This command is used
for resumed \s-1FTP\s0 transfers.
.IP "32" 1
.IX Item "32"
\&\s-1FTP\s0 couldn't use \s-1SIZE\s0. The \s-1SIZE\s0 command failed. The command is an
extension to the original \s-1FTP\s0 spec \s-1RFC\s0 959.
.IP "33" 1
.IX Item "33"
\&\s-1HTTP\s0 range error. The range \*(L"command\*(R" didn't work.
.IP "34" 1
.IX Item "34"
\&\s-1HTTP\s0 post error. Internal post-request generation error.
.IP "35" 1
.IX Item "35"
\&\s-1SSL\s0 connect error. The \s-1SSL\s0 handshaking failed.
.IP "36" 1
.IX Item "36"
\&\s-1FTP\s0 bad download resume. Couldn't continue an earlier aborted download.
.IP "37" 1
.IX Item "37"
\&\s-1FILE\s0 couldn't read file. Failed to open the file. Permissions?
.IP "38" 1
.IX Item "38"
\&\s-1LDAP\s0 cannot bind. \s-1LDAP\s0 bind operation failed.
.IP "39" 1
.IX Item "39"
\&\s-1LDAP\s0 search failed.
.IP "40" 1
.IX Item "40"
Library not found. The \s-1LDAP\s0 library was not found.
.IP "41" 1
.IX Item "41"
Function not found. A required \s-1LDAP\s0 function was not found.
.IP "42" 1
.IX Item "42"
Aborted by callback. An application told curl to abort the operation.
.IP "43" 1
.IX Item "43"
Internal error. A function was called with a bad parameter.
.IP "44" 1
.IX Item "44"
Internal error. A function was called in a bad order.
.IP "45" 1
.IX Item "45"
Interface error. A specified outgoing interface could not be used.
.IP "46" 1
.IX Item "46"
Bad password entered. An error was signaled when the password was entered.
.IP "47" 1
.IX Item "47"
Too many redirects. When following redirects, curl hit the maximum amount.
.IP "48" 1
.IX Item "48"
Unknown \s-1TELNET\s0 option specified.
.IP "49" 1
.IX Item "49"
Malformed telnet option.
.IP "51" 1
.IX Item "51"
The remote peer's \s-1SSL\s0 certificate wasn't ok
.IP "52" 1
.IX Item "52"
The server didn't reply anything, which here is considered an error.
.IP "53" 1
.IX Item "53"
\&\s-1SSL\s0 crypto engine not found
.IP "54" 1
.IX Item "54"
Cannot set \s-1SSL\s0 crypto engine as default
.IP "55" 1
.IX Item "55"
Failed sending network data
.IP "56" 1
.IX Item "56"
Failure in receiving network data
.IP "57" 1
.IX Item "57"
Share is in use (internal error)
.IP "58" 1
.IX Item "58"
Problem with the local certificate
.IP "59" 1
.IX Item "59"
Couldn't use specified \s-1SSL\s0 cipher
.IP "60" 1
.IX Item "60"
Problem with the \s-1CA\s0 cert (path? permission?)
.IP "61" 1
.IX Item "61"
Unrecognized transfer encoding
.IP "62" 1
.IX Item "62"
Invalid \s-1LDAP\s0 \s-1URL\s0
.IP "63" 1
.IX Item "63"
Maximum file size exceeded
.IP "64" 1
.IX Item "64"
Requested \s-1FTP\s0 \s-1SSL\s0 level failed
.IP "65" 1
.IX Item "65"
Sending the data requires a rewind that failed
.IP "66" 1
.IX Item "66"
Failed to initialise \s-1SSL\s0 Engine
.IP "67" 1
.IX Item "67"
User, password or similar was not accepted and curl failed to login
.IP "68" 1
.IX Item "68"
File not found on \s-1TFTP\s0 server
.IP "69" 1
.IX Item "69"
Permission problem on \s-1TFTP\s0 server
.IP "70" 1
.IX Item "70"
Out of disk space on \s-1TFTP\s0 server
.IP "71" 1
.IX Item "71"
Illegal \s-1TFTP\s0 operation
.IP "72" 1
.IX Item "72"
Unknown \s-1TFTP\s0 transfer \s-1ID\s0
.IP "73" 1
.IX Item "73"
File already exists (\s-1TFTP\s0)
.IP "74" 1
.IX Item "74"
No such user (\s-1TFTP\s0)
.IP "75" 1
.IX Item "75"
Character conversion failed
.IP "76" 1
.IX Item "76"
Character conversion functions required
.PP
There will appear more error codes here in future releases. The
existing ones are meant to never change.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\f(CWftp(1)\fR
\&\f(CWwget(1)\fR
.SH "AUTHORS"
.IX Header "AUTHORS"
Daniel Stenberg is the main author, but the whole list of contributors
is found in the separate \s-1THANKS\s0 file.
.PP
Curl homepage is at http://curl.haxx.se and the \s-1FTP\s0 access
link is ftp://ftp.sunet.se/pub/www/utilities/curl/