diff options
Diffstat (limited to 'docs/curl.1')
| -rw-r--r-- | docs/curl.1 | 598 |
1 files changed, 598 insertions, 0 deletions
diff --git a/docs/curl.1 b/docs/curl.1 new file mode 100644 index 000000000..7683a117d --- /dev/null +++ b/docs/curl.1 @@ -0,0 +1,598 @@ +.\" You can view this file with: +.\" nroff -man curl.1 +.\" Written by Daniel Stenberg +.\" +.TH curl 1 "13 March 2000" "Curl 6.5" "Curl Manual" +.SH NAME +curl \- get a URL with FTP, TELNET, LDAP, GOPHER, DICT, FILE, HTTP or +HTTPS syntax. +.SH SYNOPSIS +.B curl [options] +.I url +.SH DESCRIPTION +.B curl +is a client to get documents/files from servers, using any of the +supported protocols. 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. +.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 +.SH OPTIONS +.IP "-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. +.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. +.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 +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 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! +.IP "-B/--ftp-ascii" +(FTP/LDAP) +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". +.IP "-c/--continue" +Continue/Resume a previous file transfer. This instructs curl to +continue appending data on the file where it was previously left, +possibly because of a broken connection to the server. There must be +a named physical file to append to for this to work. +Note: Upload resume is depening on a command named SIZE not always +present in all ftp servers! Upload resume is for FTP only. +HTTP resume is only possible with HTTP/1.1 or later servers. +.IP "-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 transfered +to the destination. +If used with uploads, the ftp server command SIZE will not be used by +curl. Upload resume is for FTP only. +HTTP resume is only possible with HTTP/1.1 or later servers. +.IP "-d/--data <data>" +(HTTP) +Sends the specified data in a POST request to the HTTP server. Note +that the data is sent exactly as specified with no extra processing. +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 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. +.IP "-D/--dump-header <file>" +(HTTP/FTP) +Write the HTTP headers to this file. Write the FTP file info to this +file if -I/--head is used. + +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! +.IP "-e/--referer <URL>" +(HTTP) +Sends the "Referer Page" information to the HTTP server. Some badly +done CGIs fail if it's not set. This can also be set with the -H/--header +flag of course. +.IP "-E/--cert <certificate[:password]>" +(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! +.IP "-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. +.IP "-F/--form <name=content>" +(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 +read from a file, prefix the file name with an @ sign. 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: + +.B curl +-F password=@/etc/passwd www.mypasswords.com + +To read the file's content from stdin insted of a file, use - where the file +name should've been. +.IP "-h/--help" +Usage help. +.IP "-H/--header <header>" +(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. +.IP "-i/--include" +(HTTP) +Include the HTTP-header in the output. The HTTP-header includes things +like server-name, date of the document, HTTP-version and more... +.IP "-I/--head" +(HTTP/FTP) +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 file, curl displays the file size only. +.IP "-K/--config <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. If the first column of a config line is a '#' character, the +rest of the line will be treated as a comment. + +Specify the filename as '-' to make curl read the file from stdin. +.IP "-l/--list-only" +(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. +.IP "-L/--location" +(HTTP/HTTPS) +If the server reports that the requested page has a different location +(indicated with the header line Location:) this flag will let curl +attempt to reattempt the get on the new place. If used together with +-i or -I, headers from all requested pages will be shown. +.IP "-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. +This doesn't work properly in win32 systems. +.IP "-M/--manual" +Manual. Display the huge help text. +.IP "-n/--netrc" +Makes curl scan the +.I .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 +.BR netrc(5) +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. + +A quick and very simple example of how to setup a +.I .netrc +to allow curl to ftp to the machine host.domain.com with user name +'myself' and password 'secret' should look similar to: + +.B "machine host.domain.com login myself password secret" +.IP "-N/--no-buffer" +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. +.IP "-o/--output <file>" +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: + + curl http://{one,two}.site.com -o "file_#1.txt" + +or use several variables like: + + curl http://{site,host}.host[1-5].com -o "#1_#2" +.IP "-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.) +.IP "-P/--ftpport <address>" +(FTP) +Reverses the initiator/listener roles when connecting with ftp. This +switch makes Curl use the PORT command instead of PASV. In +practice, 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: +.RS +.TP 12 +.B interface +i.e "eth0" to specify which interface's IP address you want to use (Unix only) +.TP +.B "IP address" +i.e "192.168.10.1" to specify exact IP number +.TP +.B "host name" +i.e "my.host.domain" to specify machine +.TP +.B "-" +(any single-letter string) to make it pick the machine's default +.RE +.IP "-q" +If used as the first parameter on the command line, the +.I $HOME/.curlrc +file will not be read and used as a config file. +.IP "-Q/--quote <comand>" +(FTP) Send an arbitrary command to the remote FTP server, by using the QUOTE +command of the server. Not all servers support this command, and the set of +QUOTE commands are server specific! Quote commands are sent BEFORE the +transfer is taking place. To make commands take place after a successful +transfer, prefix them with a dash '-'. You may specify any amount of commands +to be run before and after the transfer. If the server returns failure for one +of the commands, the entire operation will be aborted. +.IP "-r/--range <range>" +(HTTP/FTP) +Retrieve a byte range (i.e a partial document) from a HTTP/1.1 or FTP +server. Ranges can be specified in a number of ways. +.RS +.TP 10 +.B 0-499 +specifies the first 500 bytes +.TP +.B 500-999 +specifies the second 500 bytes +.TP +.B -500 +specifies the last 500 bytes +.TP +.B 9500 +specifies the bytes from offset 9500 and forward +.TP +.B 0-0,-1 +specifies the first and last byte only(*)(H) +.TP +.B 500-700,600-799 +specifies 300 bytes from offset 500(H) +.TP +.B 100-199,500-599 +specifies two separate 100 bytes ranges(*)(H) +.RE + +(*) = NOTE that this will cause the server to reply with a multipart +response! + +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. + +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. +.IP "-s/--silent" +Silent mode. Don't show progress meter or error messages. Makes +Curl mute. +.IP "-S/--show-error" +When used with -s it makes curl show error message if it fails. +.IP "-t/--upload" +Transfer the stdin data to the specified file. Curl will read +everything from stdin until EOF and store with the supplied name. If +this is used on a http(s) server, the PUT command will be used. +.IP "-T/--upload-file <file>" +Like -t, but this transfers the specified local file. 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. +.IP "-u/--user <user:password>" +Specify user and password to use when fetching. See README.curl for detailed +examples of how to use this. If no password is specified, curl will +ask for it interactively. +.IP "-U/--proxy-user <user:password>" +Specify user and password to use for Proxy authentication. If no +password is specified, curl will ask for it interactively. +.IP "-v/--verbose" +Makes the fetching more verbose/talkative. Mostly usable for +debugging. Lines starting with '>' 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. +.IP "-V/--version" +Displays the full version of curl, libcurl and other 3rd party libraries +linked with the executable. +.IP "-w/--write-out <format>" +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 carrige return with \\r and a tab +space with \\t. + +.B 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: +.RS +.TP 15 +.B url_effective +The URL that was fetched last. This is mostly meaningful if you've told curl +to follow location: headers. +.TP +.B http_code +The numerical code that was found in the last retrieved HTTP(S) page. +.TP +.B time_total +The total time, in seconds, that the full operation lasted. The time will be +displayed with millisecond resolution. +.TP +.B time_namelookup +The time, in seconds, it took from the start until the name resolving was +completed. +.TP +.B time_connect +The time, in seconds, it took from the start until the connect to the remote +host (or proxy) was completed. +.TP +.B 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. +.TP +.B size_download +The total amount of bytes that were downloaded. +.TP +.B size_upload +The total amount of bytes that were uploaded. +.TP +.B speed_download +The average download speed that curl measured for the complete download. +.TP +.B speed_upload +The average upload speed that curl measured for the complete download. +.RE +.IP "-x/--proxy <proxyhost[:port]>" +Use specified proxy. If the port number is not specified, it is assumed at +port 1080. +.IP "-X/--request <command>" +(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. +.IP "-y/--speed-time <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. +.IP "-Y/--speed-limit <speed>" +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. +.IP "-z/--time-cond <date expression>" +(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 +.BR "GNU date(1)" +man page 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. +.IP "-3/--sslv3" +(HTTPS) +Forces curl to use SSL version 3 when negotiating with a remote SSL server. +.IP "-2/--sslv2" +(HTTPS) +Forces curl to use SSL version 2 when negotiating with a remote SSL server. +.IP "-#/--progress-bar" +Make curl display progress information as a progress bar instead of the +default statistics. +.IP "--crlf" +(FTP) Convert LF to CRLF in upload. Useful for MVS (OS/390). +.IP "--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. +.SH FILES +.I ~/.curlrc +.RS +Default config file. + +.SH ENVIRONMENT +.IP "HTTP_PROXY [protocol://]<host>[:port]" +Sets proxy server to use for HTTP. +.IP "HTTPS_PROXY [protocol://]<host>[:port]" +Sets proxy server to use for HTTPS. +.IP "FTP_PROXY [protocol://]<host>[:port]" +Sets proxy server to use for FTP. +.IP "GOPHER_PROXY [protocol://]<host>[:port]" +Sets proxy server to use for GOPHER. +.IP "ALL_PROXY [protocol://]<host>[:port]" +Sets proxy server to use if no protocol-specific proxy is set. +.IP "NO_PROXY <comma-separated list of hosts>" +list of host names that shouldn't go through any proxy. If set to a +asterisk '*' only, it matches all hosts. +.IP "COLUMNS <integer>" +The width of the terminal. This variable only affects curl when the +--progress-bar option is used. +.SH 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 +Unsupported protocol. This build of curl has no support for this protocol. +.IP 2 +Failed to initialize. +.IP 3 +URL malformat. The syntax was not correct. +.IP 4 +URL user malformatted. The user-part of the URL syntax was not correct. +.IP 5 +Couldn't resolve proxy. The given proxy host could not be resolved. +.IP 6 +Couldn't resolve host. The given remote host was not resolved. +.IP 7 +Failed to connect to host. +.IP 8 +FTP weird server reply. The server sent data curl couldn't parse. +.IP 9 +FTP access denied. The server denied login. +.IP 10 +FTP user/password incorrect. Either one or both were not accepted by the +server. +.IP 11 +FTP weird PASS reply. Curl couldn't parse the reply sent to the PASS request. +.IP 12 +FTP weird USER reply. Curl couldn't parse the reply sent to the USER request. +.IP 13 +FTP weird PASV reply, Curl couldn't parse the reply sent to the PASV request. +.IP 14 +FTP weird 227 formay. Curl couldn't parse the 227-line the server sent. +.IP 15 +FTP can't get host. Couldn't resolve the host IP we got in the 227-line. +.IP 16 +FTP can't reconnect. Couldn't connect to the host we got in the 227-line. +.IP 17 +FTP couldn't set binary. Couldn't change transfer method to binary. +.IP 18 +Partial file. Only a part of the file was transfered. +.IP 19 +FTP couldn't RETR file. The RETR command failed. +.IP 20 +FTP write error. The transfer was reported bad by the server. +.IP 21 +FTP quote error. A quote command returned error from the server. +.IP 22 +HTTP not found. The requested page was not found. This return code only +appears if --fail is used. +.IP 23 +Write error. Curl couldn't write data to a local filesystem or similar. +.IP 24 +Malformat user. User name badly specified. +.IP 25 +FTP couldn't STOR file. The server denied the STOR operation. +.IP 26 +Read error. Various reading problems. +.IP 27 +Out of memory. A memory allocation request failed. +.IP 28 +Operation timeout. The specified time-out period was reached according to the +conditions. +.IP 29 +FTP couldn't set ASCII. The server returned an unknown reply. +.IP 30 +FTP PORT failed. The PORT command failed. +.IP 31 +FTP couldn't use REST. The REST command failed. +.IP 32 +FTP couldn't use SIZE. The SIZE command failed. The command is an extension +to the original FTP spec RFC 959. +.IP 33 +HTTP range error. The range "command" didn't work. +.IP 34 +HTTP post error. Internal post-request generation error. +.IP 35 +SSL connect error. The SSL handshaking failed. +.IP 36 +FTP bad download resume. Couldn't continue an earlier aborted download. +.IP 37 +FILE couldn't read file. Failed to open the file. Permissions? +.IP 38 +LDAP cannot bind. LDAP bind operation failed. +.IP 39 +LDAP search failed. +.IP 40 +Library not found. The LDAP library was not found. +.IP 41 +Function not found. A required LDAP function was not found. +.IP XX +There will appear more error codes here in future releases. The existing ones +are meant to never change. +.SH BUGS +If you do find any (or have other suggestions), mail Daniel Stenberg +<Daniel.Stenberg@haxx.nu>. +.SH AUTHORS / CONTRIBUTORS + - Daniel Stenberg <Daniel.Stenberg@haxx.nu> + - Rafael Sagula <sagula@inf.ufrgs.br> + - Sampo Kellomaki <sampo@iki.fi> + - Linas Vepstas <linas@linas.org> + - Bjorn Reese <breese@mail1.stofanet.dk> + - Johan Anderson <johan@homemail.com> + - Kjell Ericson <Kjell.Ericson@haxx,nu> + - Troy Engel <tengel@sonic.net> + - Ryan Nelson <ryan@inch.com> + - Bjorn Stenberg <Bjorn.Stenberg@haxx.nu> + - Angus Mackay <amackay@gus.ml.org> + - Eric Young <eay@cryptsoft.com> + - Simon Dick <simond@totally.irrelevant.org> + - Oren Tirosh <oren@monty.hishome.net> + - Steven G. Johnson <stevenj@alum.mit.edu> + - Gilbert Ramirez Jr. <gram@verdict.uthscsa.edu> + - Andrés García <ornalux@redestb.es> + - Douglas E. Wegscheid <wegscd@whirlpool.com> + - Mark Butler <butlerm@xmission.com> + - Eric Thelin <eric@generation-i.com> + - Marc Boucher <marc@mbsi.ca> + - Greg Onufer <Greg.Onufer@Eng.Sun.COM> + - Doug Kaufman <dkaufman@rahul.net> + - David Eriksson <david@2good.com> + - Ralph Beckmann <rabe@uni-paderborn.de> + - T. Yamada <tai@imasy.or.jp> + - Lars J. Aas <larsa@sim.no> + - Jörn Hartroth <Joern.Hartroth@telekom.de> + - Matthew Clarke <clamat@van.maves.ca> + - Linus Nielsen <Linus.Nielsen@haxx.nu> + - Felix von Leitner <felix@convergence.de> + - Dan Zitter <dzitter@zitter.net> + - Jongki Suwandi <Jongki.Suwandi@eng.sun.com> + - Chris Maltby <chris@aurema.com> + - Ron Zapp <rzapper@yahoo.com> + - Paul Marquis <pmarquis@iname.com> + - Ellis Pritchard <ellis@citria.com> + - Damien Adant <dams@usa.net> + - Chris <cbayliss@csc.come> + - Marco G. Salvagno <mgs@whiz.cjb.net> +.SH WWW +http://curl.haxx.nu +.SH FTP +ftp://ftp.sunet.se/pub/www/utilities/curl/ +.SH "SEE ALSO" +.BR ftp (1), +.BR wget (1), +.BR snarf (1) |