add curl 7.16.0 to in tree libs

git-svn-id: http://svn.freeswitch.org/svn/freeswitch/trunk@3744 d0543943-73ff-0310-b7d9-9358b9ac24b2

libs/curl/docs/libcurl/libcurl.3

@@ -0,0 +1,203 @@
+.\" $Id: libcurl.3,v 1.13 2006-06-21 17:34:29 bagder Exp $
+.\"
+.TH libcurl 3 "19 March 2002" "libcurl 7.9.6" "libcurl overview"
+.SH NAME
+libcurl \- client-side URL transfers
+.SH DESCRIPTION
+This is an short overview on how to use libcurl in your C programs. There are
+specific man pages for each function mentioned in here. There are also the
+\fIlibcurl-easy(3)\fP man page, the \fIlibcurl-multi(3)\fP man page, the
+\fIlibcurl-share(3)\fP man page and the \fIlibcurl-tutorial(3)\fP man page for
+in-depth understanding on how to program with libcurl.
+
+There are more than thirty custom bindings available that bring libcurl access
+to your favourite language. Look elsewhere for documentation on those.
+
+libcurl has a global constant environment that you must set up and
+maintain while using libcurl.  This essentially means you call
+\fIcurl_global_init(3)\fP at the start of your program and
+\fIcurl_global_cleanup(3)\fP at the end.  See GLOBAL CONSTANTS below
+for details.
+
+To transfer files, you always set up an "easy handle" using
+\fIcurl_easy_init(3)\fP, but when you want the file(s) transferred you have
+the option of using the "easy" interface, or the "multi" interface.
+
+The easy interface is a synchronous interface with which you call
+\fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is
+completed, the function return and you can continue. More details are found in
+the \fIlibcurl-easy(3)\fP man page.
+
+The multi interface on the other hand is an asynchronous interface, that you
+call and that performs only a little piece of the transfer on each invoke. It
+is perfect if you want to do things while the transfer is in progress, or
+similar. The multi interface allows you to select() on libcurl action, and
+even to easily download multiple files simultaneously using a single thread. See further deails in the \fIlibcurl-multi(3)\fP man page.
+
+You can have multiple easy handles share certain data, even if they are used
+in different threads. This magic is setup using the share interface, as
+described in the \fIlibcurl-share(3)\fP man page.
+
+There is also a series of other helpful functions to use, including these:
+.RS
+.IP curl_version_info()
+gets detailed libcurl (and other used libraries) version info
+.IP curl_getdate()
+converts a date string to time_t
+.IP curl_easy_getinfo()
+get information about a performed transfer
+.IP curl_formadd()
+helps building an HTTP form POST
+.IP curl_formfree()
+free a list built with \fIcurl_formadd(3)\fP
+.IP curl_slist_append()
+builds a linked list
+.IP curl_slist_free_all()
+frees a whole curl_slist
+.RE
+
+.SH "LINKING WITH LIBCURL"
+On unix-like machines, there's a tool named curl-config that gets installed
+with the rest of the curl stuff when 'make install' is performed.
+
+curl-config is added to make it easier for applications to link with libcurl
+and developers to learn about libcurl and how to use it.
+
+Run 'curl-config --libs' to get the (additional) linker options you need to
+link with the particular version of libcurl you've installed. See the
+\fIcurl-config(1)\fP man page for further details.
+
+Unix-like operating system that ship libcurl as part of their distributions
+often don't provide the curl-config tool, but simply install the library and
+headers in the common path for this purpose.
+
+.SH "LIBCURL SYMBOL NAMES"
+All public functions in the libcurl interface are prefixed with 'curl_' (with
+a lowercase c). You can find other functions in the library source code, but
+other prefixes indicate that the functions are private and may change without
+further notice in the next release.
+
+Only use documented functions and functionality!
+.SH "PORTABILITY"
+libcurl works
+.B exactly
+the same, on any of the platforms it compiles and builds on.
+.SH "THREADS"
+Never ever call curl-functions simultaneously using the same handle from
+several threads. libcurl is thread-safe and can be used in any number of
+threads, but you must use separate curl handles if you want to use libcurl in
+more than one thread simultaneously.
+
+The global environment functions are not thread-safe.  See GLOBAL CONSTANTS
+below for details.
+
+.SH "PERSISTENT CONNECTIONS"
+Persistent connections means that libcurl can re-use the same connection for
+several transfers, if the conditions are right.
+
+libcurl will \fBalways\fP attempt to use persistent connections. Whenever you
+use \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP, libcurl will
+attempt to use an existing connection to do the transfer, and if none exists
+it'll open a new one that will be subject for re-use on a possible following
+call to \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP.
+
+To allow libcurl to take full advantage of persistent connections, you should
+do as many of your file transfers as possible using the same curl handle. When
+you call \fIcurl_easy_cleanup(3)\fP, all the possibly open connections held by
+libcurl will be closed and forgotten.
+
+Note that the options set with \fIcurl_easy_setopt(3)\fP will be used in on
+every repeated \fIcurl_easy_perform(3)\fP call.
+
+.SH "GLOBAL CONSTANTS"
+There are a variety of constants that libcurl uses, mainly through its
+internal use of other libraries, which are too complicated for the
+library loader to set up.  Therefore, a program must call a library
+function after the program is loaded and running to finish setting up
+the library code.  For example, when libcurl is built for SSL
+capability via the GNU TLS library, there is an elaborate tree inside
+that library that describes the SSL protocol.
+
+\fIcurl_global_init()\fP is the function that you must call.  This may
+allocate resources (e.g. the memory for the GNU TLS tree mentioned
+above), so the companion function \fIcurl_global_cleanup()\fP releases
+them.
+
+The basic rule for constructing a program that uses libcurl is this:
+Call \fIcurl_global_init()\fP, with a \fICURL_GLOBAL_ALL\fP argument,
+immediately after the program starts, while it is still only one
+thread and before it uses libcurl at all.  Call
+\fIcurl_global_cleanup()\fP immediately before the program exits, when
+the program is again only one thread and after its last use of
+libcurl.
+
+You can call both of these multiple times, as long as all calls meet
+these requirements and the number of calls to each is the same.
+
+It isn't actually required that the functions be called at the beginning
+and end of the program -- that's just usually the easiest way to do it.
+It \fIis\fP required that the functions be called when no other thread
+in the program is running.
+
+These global constant functions are \fInot thread safe\fP, so you must
+not call them when any other thread in the program is running.  It
+isn't good enough that no other thread is using libcurl at the time,
+because these functions internally call similar functions of other
+libraries, and those functions are similarly thread-unsafe.  You can't
+generally know what these libraries are, or whether other threads are
+using them.
+
+The global constant situation merits special consideration when the
+code you are writing to use libcurl is not the main program, but rather
+a modular piece of a program, e.g. another library.  As a module,
+your code doesn't know about other parts of the program -- it doesn't
+know whether they use libcurl or not.  And its code doesn't necessarily
+run at the start and end of the whole program.
+
+A module like this must have global constant functions of its own,
+just like \fIcurl_global_init()\fP and \fIcurl_global_cleanup()\fP.
+The module thus has control at the beginning and end of the program
+and has a place to call the libcurl functions.  Note that if multiple
+modules in the program use libcurl, they all will separately call the
+libcurl functions, and that's OK because only the first
+\fIcurl_global_init()\fP and the last \fIcurl_global_cleanup()\fP in a
+program changes anything.  (libcurl uses a reference count in static
+memory).
+
+In a C++ module, it is common to deal with the global constant
+situation by defining a special class that represents the global
+constant environment of the module.  A program always has exactly one
+object of the class, in static storage.  That way, the program
+automatically calls the constructor of the object as the program
+starts up and the destructor as it terminates.  As the author of this
+libcurl-using module, you can make the constructor call
+\fIcurl_global_init()\fP and the destructor call
+\fIcurl_global_cleanup()\fP and satisfy libcurl's requirements without
+your user having to think about it.
+
+\fIcurl_global_init()\fP has an argument that tells what particular
+parts of the global constant environment to set up.  In order to
+successfully use any value except \fICURL_GLOBAL_ALL\fP (which says to
+set up the whole thing), you must have specific knowledge of internal
+workings of libcurl and all other parts of the program of which it is
+part.
+
+A special part of the global constant environment is the identity of
+the memory allocator.  \fIcurl_global_init()\fP selects the system
+default memory allocator, but you can use \fIcurl_global_init_mem()\fP
+to supply one of your own.  However, there is no way to use
+\fIcurl_global_init_mem()\fP in a modular program -- all modules in
+the program that might use libcurl would have to agree on one
+allocator.
+
+There is a failsafe in libcurl that makes it usable in simple
+situations without you having to worry about the global constant
+environment at all: \fIcurl_easy_init()\fP sets up the environment
+itself if it hasn't been done yet.  The resources it acquires to do so
+get released by the operating system automatically when the program
+exits.
+
+This failsafe feature exists mainly for backward compatibility because
+there was a time when the global functions didn't exist.  Because it
+is sufficient only in the simplest of programs, it is not recommended
+for any program to rely on it.