libcurl - client-side URL transfers


DESCRIPTION

       This  is  an overview on how to use libcurl in your C pro-
       grams. There are specific man pages for each function men-
       tioned  in here. There are also the libcurl-easy man page,
       the libcurl-multi man page, the libcurl-share man page and
       the  libcurl-the-guide document for further reading on how
       to do programming with libcurl.

       There exist more than a dozen custom bindings  that  bring
       libcurl  access to your favourite language. Look elsewhere
       for documentation on those.

       All   applications   that   use   libcurl   should    call
       curl_global_init()  exactly  once before any libcurl func-
       tion can be used. After all usage of libcurl is  complete,
       it  must  call curl_global_cleanup(). In between those two
       calls, you can use libcurl as described below.

       To transfer files, you always  set  up  an  "easy  handle"
       using  curl_easy_init(),  but  when  you  want the file(s)
       transfered you have the option of using the "easy"  inter-
       face, or the "multi" interface.

       The  easy  interface is a synchronous interface with which
       you call curl_easy_perform and let it perform  the  trans-
       fer. When it is completed, the function return and you can
       continue. More details are found in the  libcurl-easy  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 tranfer 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.

       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
       libcurl-share man page.

       There is also a series of other helpful functions to  use.
       They are:


              curl_version()
                        displays the libcurl version

              curl_getdate()
                        portable environment variable reader

              curl_easy_getinfo()
                        get  information about a performed trans-
                        fer

              curl_formadd()
                        helps building a HTTP form POST

              curl_formfree()
                        free  a  list   built   with   curl_form-
                        parse()/curl_formadd()

              curl_slist_append()
                        builds a linked list

              curl_slist_free_all()
                        frees a whole curl_slist

              curl_mprintf()
                        portable printf() functions

              curl_strequal()
                        portable  case insensitive string compar-
                        isons



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.

       For details, see the curl-config.1 man page.


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  the functions are private and may change without
       further notice in the next release.

       Only use documented functions and functionality!


PORTABILITY



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.


PERSISTANT CONNECTIONS

       Persistent  connections  means that libcurl can re-use the
       same connection for several transfers, if  the  conditions
       are right.

       libcurl  will  *always*  attempt to use persistent connec-
       tions.   Whenever   you   use    curl_easy_perform()    or
       curl_multi_perform(),  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   curl_easy_perform()   or
       curl_multi_perform().

       To allow libcurl to take full advantage of persistent con-
       nections, you should do as many of your file transfers  as
       possible  using  the  same  curl  handle.  When  you  call
       curl_easy_cleanup(), all  the  possibly  open  connections
       held by libcurl will be closed and forgotten.

       Note  that the options set with curl_easy_setopt() will be
       used in on every repeated curl_easy_perform() call.
























Man(1) output converted with man2html