updated, improved language at a few places

                                       Updated for curl 7.7.2 on April 26, 2001

                                       Updated for curl 7.8 on May 29, 2001

                                  _   _ ____  _     

                              ___| | | |  _ \| |    

                             / __| | | | |_) | |    

 rather small and easy-to-follow. All the ones prefixed with 'curl_easy' are

 put in the lib/easy.c file.

 Starting with libcurl 7.8, curl_global_init_() and curl_global_cleanup() were

 introduced. They should be called by the application to initialize and clean

 up global stuff in the library. As of today, they just do the global SSL

 initing if SSL is enabled. libcurl itself has no "global" scope.

 All printf()-style functions use the supplied clones in lib/mprintf.c. This

 makes sure we stay absolutely platform independent.

 curl_easy_init() allocates an internal struct and makes some initializations.

 The returned handle does not reveal internals.

 The returned handle does not reveal internals. This is the 'UrlData' struct

 which works as a global "anchor" struct. All connections performed will get

 connect-specific data allocated that should be used for things related to

 particular connections/requests.

 curl_easy_setopt() takes a three arguments, where the option stuff must be

 passed in pairs, the parameter-ID and the parameter-value. The list of

 options is documented in the man page.

 curl_easy_setopt() takes three arguments, where the option stuff must be

 passed in pairs: the parameter-ID and the parameter-value. The list of

 options is documented in the man page. This function mainly sets things in

 the 'UrlData' struct.

 curl_easy_perform() does a whole lot of things:

 It starts off in the lib/easy.c file by calling Curl_perform() and the main

 work then continues lib/url.c. The flow continues with a call to

 work then continues in lib/url.c. The flow continues with a call to

 Curl_connect() to connect to the remote site.

 o Curl_connect()

   When Curl_connect is done, we are connected to the remote site. Then it is

   time to tell the server to get a document/file. Curl_do() arranges this.

   This function makes sure there's an allocated and initiated 'connectdata'

   struct that is used for this particular connection only (although there may

   be several requests performed on the same connect). A bunch of things are

   inited/inherited from the UrlData struct.

 o Curl_do()

   Curl_do() makes sure the proper protocol-specific function is called. The

   functions are named after the protocols they handle. Curl_ftp(),

   Curl_http(), Curl_dict(), etc. They all reside in their respective files

   (ftp.c, http.c and dict.c).

   (ftp.c, http.c and dict.c). HTTPS is handled by Curl_http() and FTPS by

   Curl_ftp().

   The protocol-specific functions of course deal with protocol-specific

   negotiations and setup. They have access to the Curl_sendf() (from

   Called after a transfer is done. This function takes care of everything

   that has to be done after a transfer. This function attempts to leave

   matters in a state so that Curl_do() should be possible to call again on

   the same connection (in a persistent connection case). It may also soon be

   closed with Curl_disconnect().

   the same connection (in a persistent connection case). It might also soon

   be closed with Curl_disconnect().

 o Curl_disconnect()

   During normal connection and transfers, no one ever tries to close any

   When doing normal connections and transfers, no one ever tries to close any

   connection so this is not normally called when curl_easy_perform() is

   used. This function is only used when we are certain that no more transfers

   is going to be made on the connection (it can be also closed by

   force). This function can also be called at times to make sure that libcurl

   doesn't keep too many connections alive at the same time.

   is going to be made on the connection. It can be also closed by force, or

   it can be called to make sure that libcurl doesn't keep too many

   connections alive at the same time (there's a default amount of 5 but that

   can be changed with the CURLOPT_MAXCONNECTS option).

   This function cleans up all resources that are associated with a single

   connection.

Persistent Connections

======================

 With curl 7.7, we added persistent connection support to libcurl which has

 introduced a somewhat different treatmeant of things inside of libcurl.

 The persistent connection support in libcurl requires some considerations on

 how to do things inside of the library.

 o The 'UrlData' struct returned in the curl_easy_init() call must never

   hold connection-oriented data. It is meant to hold the root data as well

   as all the options etc that the library-user may choose.

 o The 'UrlData' struct holds the cache array of pointers to 'connectdata'

   structs. There's one connectdata struct for each connection that libcurl

   knows about.

 o The 'UrlData' struct holds the "connection cache" (an array of pointers to

   'connectdata' structs). There's one connectdata struct allocated for each

   connection that libcurl knows about.

 o This also enables the 'curl handle' to be reused on subsequent transfers,

   something that was illegal in pre-7.7 versions.

   something that was illegal before libcurl 7.7.

 o When we are about to perform a transfer with curl_easy_perform(), we first

   check for an already existing connection in the cache that we can use,

   otherwise we create a new one and add to the cache. If the cache is full

   already when we add a new connection, we close one of the present ones. We

   select which one to close dependent on the close policy that may have been

   previously set.

 o When the tranfer operation is complete, we try to leave the connection open.

   Particular options may tell us not to, and protocols may signal closure on

   connections and then we don't keep it open of course.

 o When the transfer operation is complete, we try to leave the connection

   open. Particular options may tell us not to, and protocols may signal

   closure on connections and then we don't keep it open of course.

 o When curl_easy_cleanup() is called, we close all still opened connections.

 You do realize that the curl handle must be re-used in order for the

===============

 All symbols used internally in libcurl must use a 'Curl_' prefix if they're

 used in more than a single file. Single-file symbols must be made

 static. Public (exported) symbols must use a 'curl_' prefix. (There are

 exceptions, but they are destined to be changed to follow this pattern in the

 future.)

 used in more than a single file. Single-file symbols must be made static.

 Public ("exported") symbols must use a 'curl_' prefix. (There are exceptions,

 but they are to be changed to follow this pattern in future versions.)

Return Codes and Informationals

===============================