Linux / Unix Command: curl
Command Library
NAME
curl - transfer a URL
SYNOPSIS
curl [options] [URL...]
DESCRIPTION
curl is a client to get documents/files from or send documents to a server, using any of the supported protocols (HTTP, HTTPS, FTP, GOPHER, DICT, TELNET, LDAP or FILE). The command is designed to work without user interaction or any kind of interactivity.
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.
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.
OPTIONS
-a/--append
(FTP) When used in a 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.
-A/--user-agent
(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.
-b/--cookie
(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 -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.
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.
-B/--use-ascii
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.
--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: http://www.openssl.org/docs/apps/ciphers.html (Option added in curl 7.9)
If this option is used severl times, the last one will override the others.
--connect-timeout
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 --max-time option.
If this option is used several times, the last one will be used.
-c/--cookie-jar
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 be written to stdout. (Option added in curl 7.9)
If this option is used several times, the last specfied file name will be used.
-C/--continue-at
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.
--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.
-d/--data
(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 append data.
--data-ascii
(HTTP) This is an alias for the -d/--data option.
If this option is used several times, the ones following the first will append data.
--data-binary
(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 append data.
--disable-epsv
(FTP) Tell curl to disable the use of the EPSV command when doing passive FTP downloads. Curl will normally always first attempt to use EPSV before PASV, but with this option, it will not try using EPSV.
If this option is used several times, each occurrence will toggle this on/off.
-D/--dump-header
Write the protocol headers to the specified file.
This option is handy to use when you want to store the cookies that a HTTP site sends to you. The cookies could then be read in a second curl invoke by using the -b/--cookie option!
When used on FTP, the ftp server response lines are considered being "headers" and thus are saved there.
If this option is used several times, the last one will be used.
-e/--referer
(HTTP) Sends the "Referer Page" information to the HTTP server. This can also be set with the -H/--header flag of course. When used with -L/--location 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.
If this option is used several times, the last one will be used.
--environment
(RISC OS ONLY) Sets a range of environment variables, using the names the -w option supports, to easier allow extraction of useful information after having run curl.
If this option is used several times, each occurrence will toggle this on/off.
--egd-file
(HTTPS) 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 --random-file option.
-E/--cert
(HTTPS) Tells curl to use the specified certificate file when getting a file with HTTPS. The certificate must be in PEM 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!
If this option is used several times, the last one will be used.
--cacert
(HTTPS) 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.
If this option is used several times, the last one will be used.
--capath
(HTTPS) 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. Certificate directories are not supported under Windows (because c_rehash uses symbolink links to create them). Using --capath can allow curl to make https connections much more efficiently than using --cacert if the --cacert file contains many CA certificates.
If this option is used several times, the last one will be used.
-f/--fail
(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 a HTML document stating so (which often also describes why and more). This flag will prevent curl from outputting that and fail silently instead.
If this option is used twice, the second will again disable silent failure.
-F/--form
(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 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 ' means data sent by curl, '<' means data received by curl that is hidden in normal cases and lines starting with '*' means additional info provided by curl.
If this option is used twice, the second will again disable verbose.
-V/--version
Displays the full version of curl, libcurl and other 3rd party libraries linked with the executable.
-w/--write-out
Defines what to display 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 "@-".
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.
NOTE: The %-letter is a special letter in the win32-environment, where all occurrences of % must be doubled when using this option.
Available variables are at this point:
url_effective
The URL that was fetched last. This is mostly meaningful if you've told curl to follow location: headers.
http_code
The numerical code that was found in the last retrieved HTTP(S) page.
time_total
The total time, in seconds, that the full operation lasted. The time will be displayed with millisecond resolution.
time_namelookup
The time, in seconds, it took from the start until the name resolving was completed.
time_connect
The time, in seconds, it took from the start until the connect to the remote host (or proxy) was completed.
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.
time_starttransfer
The time, in seconds, it took from the start until the first byte is just about to be transfered. This includes time_pretransfer and also the time the server needs to calculate the result.
size_download
The total amount of bytes that were downloaded.
size_upload
The total amount of bytes that were uploaded.
size_header
The total amount of bytes of the downloaded headers.
size_request
The total amount of bytes that were sent in the HTTP request.
speed_download
The average download speed that curl measured for the complete download.
speed_upload
The average upload speed that curl measured for the complete upload.
content_type
The Content-Type of the requested document, if there was any. (Added in 7.9.5)
If this option is used several times, the last one will be used.
-x/--proxy
Use specified HTTP proxy. If the port number is not specified, it is assumed at port 1080.
Note that all operations that are performed over a HTTP proxy will transparantly 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 -p/--proxytunnel option.
If this option is used several times, the last one will be used.
-X/--request
(HTTP) Specifies a custom request to use when communicating with the HTTP server. The specified request will be used instead of the standard GET. Read the HTTP 1.1 specification for details and explanations.
(FTP) Specifies a custom FTP command to use instead of LIST when doing file lists with ftp.
If this option is used several times, the last one will be used.
-y/--speed-time
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.
If this option is used several times, the last one will be used.
-Y/--speed-limit
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.
If this option is used several times, the last one will be used.
-z/--time-cond
(HTTP) Request to get 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 GNU date(1) or curl_getdate(3) man pages for date expression details.
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.
If this option is used several times, the last one will be used.
-Z/--max-redirs
Set maximum number of redirection-followings allowed. If -L/--location is used, this option can be used to prevent curl from following redirections "in absurdum".
If this option is used several times, the last one will be used.
-3/--sslv3
(HTTPS) Forces curl to use SSL version 3 when negotiating with a remote SSL server.
-2/--sslv2
(HTTPS) Forces curl to use SSL version 2 when negotiating with a remote SSL server.
-0/--http1.0
(HTTP) Forces curl to issue its requests using HTTP 1.0 instead of using its internally preferred: HTTP 1.1.
-#/--progress-bar
Make curl display progress information as a progress bar instead of the default statistics.
If this option is used twice, the second will again disable the progress bar.
亚狐科技YAHUHOST
http://www.yahuhost.com
http://www.yahuhost.net