                                  _   _ ____  _     
  Project                     ___| | | |  _ \| |    
                             / __| | | | |_) | |    
                            | (__| |_| |  _ <| |___ 
                             \___|\___/|_| \_\_____|

NAME
  curl - get a file from a FTP, GOPHER or HTTP server.

SYNOPSIS
  curl [options] <url>
 
DESCRIPTION
  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.

OPTIONS
   The following options may be specified at the command line:

   -a   (FTP ONLY)
        When used in a ftp upload, this will curl to append to the target
        file instead of overwriting it. If the file doesn't exist, it will
        be created.

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

   -c   (FTP ONLY)
	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!

   -C <offset> (FTP ONLY)
	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.

   -d <data> (HTTP ONLY)
        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 "urlencoded".

   -e <url> (HTTP ONLY)
        Sends the "Referer Page" information to the HTTP server. Some badly
        done CGIs fail if it's not set.

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

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

   -I   (HTTP ONLY)
        Fetch the HTTP-header only! HTTP-servers feature the command HEAD
        which this uses to get nothing but the header of a document.

   -k   (HTTP ONLY)
        Use Keep-Alive connection. There is currently no real gain to use
        this.

   -l   (FTP ONLY)
        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.

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

   -n
	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, but
	if used with http and curl user authentication will be switched
	on. See man netrc(4) 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.

   -o <file>
        Write output to <file> instead of stdout.

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

   -r <range>   (HTTP ONLY)
        Retrieve a byte range (i.e a partial document) from a HTTP/1.1
        server. Ranges can be specified in a number of ways.
        0-499           - specifies the first 500 bytes
        500-999         - specifies the second 500 bytes
        -500            - specifies the last 500 bytes
        9500-           - specifies the bytes from offset 9500 and forward
        0-0,-1          - specifies the first and last byte only(*)
        500-700,600-799 - specifies 300 bytes from offset 500
        100-199,500-599 - specifies two separate 100 bytes ranges(*)

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

   -p <port>
        Use port other than default for current protocol. This is typically
        most used together with the proxy-flag (-x).

   -P <address> (FTP ONLY)
	Reverses the initiator/listenor 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:
          interface - i.e "eth0" to specify which interface's IP address you
                      want to use  (Unix only)
          IP address - i.e "192.168.10.1" to specify exact IP number
          host name - i.e "my.host.domain" to specify machine
          "-"       - (any single-letter string) to make it pick the machine's
                      default

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

   -sl <speed>
	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 -st and is 30 if not set.

   -st <time>
	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 -sl.

   -t  (FTP only)
	Transfer the stdin data to the specified file. Curl will read
	everything from stdin until EOF and store with the supplied name.

   -T <file> (FTP)
        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.

   -T <file> (HTTP and HTTPS)
        Specify a file containing raw HTTP comands. Typically, this file
        will have a POST header including Content-Type and Content-Length
        fields, and then a blank line followed by POST data.

   -u <user:password>
        Specify user and password to use when fetching. See below for detailed
        examples of how to use this.

   -U <user:password>
        Specify user and password to use for Proxy authentication.

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

   -x <proxyhost>
   -x <proxyhost:proxyport>
        Use proxy. If the proxyport is not specified, and the -p flag is not
        used, it is assumed the proxy is at port 1080.  If the -p flag is
        used, then that indicated port number is assumed to be the proxy port
        number.

SIMPLE USAGE

  Get the main page from netscape's web-server:

        curl http://www.netscape.com/

  Get the root README file from funet's ftp-server:

        curl ftp://ftp.funet.fi/README

  Get a gopher document from funet's gopher server:

        curl gopher://gopher.funet.fi

  Get a web page from a server using port 8000:

        curl http://www.weirdserver.com:8000/

  Get a list of the root directory of an FTP site:

        curl ftp://ftp.fts.frontec.se/

DOWNLOAD TO A FILE

  Get a web page and store in a local file:

        curl -o thatpage.html http://www.netscape.com/

  Get a web page and store in a local file, make the local file get the name
  of the remote document (if no file name part is specified in the URL, this
  will fail):

        curl -O http://www.netscape.com/index.html

USING PASSWORDS

 FTP

   To ftp files using name+passwd, include them in the URL like:

        curl ftp://name:passwd@machine.domain:port/full/path/to/file

   or specify them with the -u flag like

        curl -u name:passwd ftp://machine.domain:port/full/path/to/file

 HTTP

   The HTTP URL doesn't support user and password in the URL string. Curl
   does support that anyway to provide a ftp-style interface and thus you can
   pick a file like:

        curl http://name:passwd@machine.domain/full/path/to/file

   or specify user and password separately like in

        curl -u name:passwd http://machine.domain/full/path/to/file

   NOTE! Since HTTP URLs don't support user and password, you can't use that
   style when using Curl via a proxy. You _must_ use the -u style fetch
   during such circumstances.

 GOPHER

   Curl features no password support for gopher.

PROXY

 Get a web page using a proxy named my-proxy that uses port 888:

        curl -p 888 -x my-proxy http://www.web.com/

 Get an ftp file using a proxy named my-proxy that uses port 888:

        curl -p 888 -x my-proxy ftp://ftp.leachsite.com/README

 Get a file from a HTTP server that requires user and password, using the
 same proxy as above:

        curl -u user:passwd -p 888 -x my-proxy http://www.get.this/

RANGES

  With HTTP 1.1 byte-ranges were introduced. Using this, a client can request
  to get only one or more subparts of a specified document. Curl supports
  this with the -r flag.

  Get the first 100 bytes of a document:

        curl -r 0-99 http://www.get.this/

  Get the last 500 bytes of a document:

        curl -r -500 http://www.get.this/

UPLOADING

 FTP

   Upload all data on stdin to a specified ftp site:

        curl -t ftp://ftp.upload.com/myfile

   Upload data from a specified file, login with user and password:

        curl -T uploadfile -u user:passwd ftp://ftp.upload.com/myfile

   Upload a local file to the remote site, and use the local file name remote
   too:
 
        curl -T uploadfile -u user:passwd ftp://ftp.upload.com/

 HTTP

   See the POST section below.

VERBOSE / DEBUG

  If curl fails where it isn't supposed to, if the servers don't let you
  in, if you can't understand the responses: use the -v flag to get VERBOSE
  fetching. Curl will output lots of info and all data it sends and
  receives in order to let the user see all client-server interaction.

        curl -v ftp://ftp.upload.com/

POST

  It's easy to post data using curl. This is done using the -d <data>
  option.  The post data must be urlencoded.

  Post a simple "name" and "phone" guestbook.

  curl -d "name=Rafael%20Sagula&phone=3320780" http://www.where.com/guest.cgi

REFERER

  A HTTP request has the option to include information about which address
  that referred to actual page, and curl allows the user to specify that
  referrer to get specified on the command line. It is especially useful to
  fool or trick stupid servers or CGI scripts that rely on that information
  being available or contain certain data.

	curl -e www.coolsite.com http://www.showme.com/

USER AGENT

  A HTTP request has the option to include information about the browser
  that generated the request. Curl allows it to be specified on the command
  line. It is especially useful to fool or trick stupid servers or CGI
  scripts that only accept certain browsers.

  Example:

  curl -A 'Mozilla/3.0 (Win95; I)' http://www.nationsbank.com/

  Other common strings:
    'Mozilla/3.0 (Win95; I)'     Netscape Version 3 for Windows 95
    'Mozilla/3.04 (Win95; U)'    Netscape Version 3 for Windows 95
    'Mozilla/2.02 (OS/2; U)'     Netscape Version 2 for OS/2
    'Mozilla/4.04 [en] (X11; U; AIX 4.2; Nav)'           NS for AIX
    'Mozilla/4.05 [en] (X11; U; Linux 2.0.32 i586)'      NS for Linux

  Note that Internet Explorer tries hard to be compatible in every way:
    'Mozilla/4.0 (compatible; MSIE 4.01; Windows 95)'    MSIE for W95

  Mozilla is not the only possible User-Agent name:
    'Konqueror/1.0'             KDE File Manager desktop client
    'Lynx/2.7.1 libwww-FM/2.14' Lynx command line browser

PROGRESS METER

  The progress meter was introduced to better show a user that something
  actually is happening. The different fields in the output have the following
  meaning:

   %   Received   Total  Speed   Time left  Total   Curr.Speed
  13   524140   3841536   4296   0:12:52   0:14:54    292     

  From left-to-right:
  - The first column, is the percentage of the file currently transfered.
  - Received means the total number of bytes that has been transfered.
  - Total is the total number of bytes expected to transfer.
  - Speed is average speed in bytes per second for the whole transfer so far.
  - Time left is the estimated time left for this transfer to finnish if the
    current average speed will remain steady.
  - Total is the estimated total transfer time.
  - Curr.Speed is the average transfer speed the last 5 seconds (the first
    5 seconds of a transfer is based on less time of course.)

  NOTE: Much of the output is based on the fact that the size of the transfer
  is known before it takes place. If it isn't, a much less fancy display will
  be used.

SPEED LIMIT

  Curl offers the user to set conditions regarding transfer speed that must
  be met to let the transfer keep going. By using the switch -sl and -st you
  can make curl abort transfers if the transfer speed doesn't exceed your
  given lowest limit for a specified time.

  To let curl abandon downloading this page if its slower than 3000 bytes per
  second for 1 minute, run:

	curl -sl 3000 -st 60 www.far-away-site.com

  This can very well be used in combination with the overall time limit, so
  that the above operatioin must be completed in whole within 30 minutes:

	curl -m 1800 -sl 3000 -st 60 www.far-away-site.com

BUGS
  Nope. :-) But don't try excessive string lengths, we don't do many boundary
  checks so those will without doubt crash this.

  Well, if you do find any (or have other suggestions), mail Daniel Stenberg
  <Daniel.Stenberg@sth.frontec.se>.

VERSION
  This document attempts to describe the usage of curl 4.7 and later.
  Written by Daniel Stenberg and Linas Vepstas.

AUTHORS
  Daniel Stenberg <Daniel.Stenberg@sth.frontec.se>
  Rafael Sagula <sagula@inf.ufrgs.br>
  Sampo Kellomaki <sampo@iki.fi>
  Linas Vepstas <linas@linas.org>
  Bjorn Reese <breese@imada.ou.dk>
  Johan Anderson <johan@homemail.com>
  Kjell Ericson <Kjell.Ericson@sth.frontec.se>
    
WWW
  http://www.fts.frontec.se/~dast/curl/
  http://www.inf.ufrgs.br/~sagula/urlget.html
