Return to libcurl.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl

curl

    1: .\" **************************************************************************
    2: .\" *                                  _   _ ____  _
    3: .\" *  Project                     ___| | | |  _ \| |
    4: .\" *                             / __| | | | |_) | |
    5: .\" *                            | (__| |_| |  _ <| |___
    6: .\" *                             \___|\___/|_| \_\_____|
    7: .\" *
    8: .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
    9: .\" *
   10: .\" * This software is licensed as described in the file COPYING, which
   11: .\" * you should have received as part of this distribution. The terms
   12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
   13: .\" *
   14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
   15: .\" * copies of the Software, and permit persons to whom the Software is
   16: .\" * furnished to do so, under the terms of the COPYING file.
   17: .\" *
   18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
   19: .\" * KIND, either express or implied.
   20: .\" *
   21: .\" **************************************************************************
   22: .TH libcurl 3 "March 23, 2020" "libcurl 7.70.0" "libcurl overview"
   23: 
   24: .SH NAME
   25: libcurl \- client-side URL transfers
   26: .SH DESCRIPTION
   27: This is a short overview on how to use libcurl in your C programs. There are
   28: specific man pages for each function mentioned in here. There are also the
   29: \fIlibcurl-easy(3)\fP man page, the \fIlibcurl-multi(3)\fP man page, the
   30: \fIlibcurl-share(3)\fP man page and the \fIlibcurl-tutorial(3)\fP man page for
   31: in-depth understanding on how to program with libcurl.
   32: 
   33: There are many bindings available that bring libcurl access to your favourite
   34: language. Look elsewhere for documentation on those.
   35: 
   36: libcurl has a global constant environment that you must set up and maintain
   37: while using libcurl.  This essentially means you call
   38: \fIcurl_global_init(3)\fP at the start of your program and
   39: \fIcurl_global_cleanup(3)\fP at the end.  See \fBGLOBAL CONSTANTS\fP below for
   40: details.
   41: 
   42: If libcurl was compiled with support for multiple SSL backends, the function
   43: \fIcurl_global_sslset(3)\fP can be called before \fIcurl_global_init(3)\fP
   44: to select the active SSL backend.
   45: 
   46: To transfer files, you create an "easy handle" using \fIcurl_easy_init(3)\fP
   47: for a single individual transfer (in either direction). You then set your
   48: desired set of options in that handle with \fIcurl_easy_setopt(3)\fP. Options
   49: you set with \fIcurl_easy_setopt(3)\fP stick. They will be used on every
   50: repeated use of this handle until you either change the option, or you reset
   51: them all with \fIcurl_easy_reset(3)\fP.
   52: 
   53: To actually transfer data you have the option of using the "easy" interface,
   54: or the "multi" interface.
   55: 
   56: The easy interface is a synchronous interface with which you call
   57: \fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is
   58: completed, the function returns and you can continue. More details are found in
   59: the \fIlibcurl-easy(3)\fP man page.
   60: 
   61: The multi interface on the other hand is an asynchronous interface, that you
   62: call and that performs only a little piece of the transfer on each invoke. It
   63: is perfect if you want to do things while the transfer is in progress, or
   64: similar. The multi interface allows you to select() on libcurl action, and
   65: even to easily download multiple files simultaneously using a single
   66: thread. See further details in the \fIlibcurl-multi(3)\fP man page.
   67: 
   68: You can have multiple easy handles share certain data, even if they are used
   69: in different threads. This magic is setup using the share interface, as
   70: described in the \fIlibcurl-share(3)\fP man page.
   71: 
   72: There is also a series of other helpful functions to use, including these:
   73: .RS
   74: .IP curl_version_info()
   75: gets detailed libcurl (and other used libraries) version info
   76: .IP curl_getdate()
   77: converts a date string to time_t
   78: .IP curl_easy_getinfo()
   79: get information about a performed transfer
   80: .IP curl_formadd()
   81: helps building an HTTP form POST
   82: .IP curl_formfree()
   83: free a list built with \fIcurl_formadd(3)\fP
   84: .IP curl_slist_append()
   85: builds a linked list
   86: .IP curl_slist_free_all()
   87: frees a whole curl_slist
   88: .RE
   89: 
   90: .SH "LINKING WITH LIBCURL"
   91: On unix-like machines, there's a tool named curl-config that gets installed
   92: with the rest of the curl stuff when 'make install' is performed.
   93: 
   94: curl-config is added to make it easier for applications to link with libcurl
   95: and developers to learn about libcurl and how to use it.
   96: 
   97: Run 'curl-config --libs' to get the (additional) linker options you need to
   98: link with the particular version of libcurl you've installed. See the
   99: \fIcurl-config(1)\fP man page for further details.
  100: 
  101: Unix-like operating system that ship libcurl as part of their distributions
  102: often don't provide the curl-config tool, but simply install the library and
  103: headers in the common path for this purpose.
  104: 
  105: Many Linux and similar systems use pkg-config to provide build and link
  106: options about libraries and libcurl supports that as well.
  107: .SH "LIBCURL SYMBOL NAMES"
  108: All public functions in the libcurl interface are prefixed with 'curl_' (with
  109: a lowercase c). You can find other functions in the library source code, but
  110: other prefixes indicate that the functions are private and may change without
  111: further notice in the next release.
  112: 
  113: Only use documented functions and functionality!
  114: .SH "PORTABILITY"
  115: libcurl works
  116: .B exactly
  117: the same, on any of the platforms it compiles and builds on.
  118: .SH "THREADS"
  119: libcurl is thread safe but there are a few exceptions. Refer to
  120: \fIlibcurl-thread(3)\fP for more information.
  121: 
  122: .SH "PERSISTENT CONNECTIONS"
  123: Persistent connections means that libcurl can re-use the same connection for
  124: several transfers, if the conditions are right.
  125: 
  126: libcurl will \fBalways\fP attempt to use persistent connections. Whenever you
  127: use \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl
  128: will attempt to use an existing connection to do the transfer, and if none
  129: exists it'll open a new one that will be subject for re-use on a possible
  130: following call to \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP.
  131: 
  132: To allow libcurl to take full advantage of persistent connections, you should
  133: do as many of your file transfers as possible using the same handle.
  134: 
  135: If you use the easy interface, and you call \fIcurl_easy_cleanup(3)\fP, all
  136: the possibly open connections held by libcurl will be closed and forgotten.
  137: 
  138: When you've created a multi handle and are using the multi interface, the
  139: connection pool is instead kept in the multi handle so closing and creating
  140: new easy handles to do transfers will not affect them. Instead all added easy
  141: handles can take advantage of the single shared pool.
  142: .SH "GLOBAL CONSTANTS"
  143: There are a variety of constants that libcurl uses, mainly through its
  144: internal use of other libraries, which are too complicated for the
  145: library loader to set up.  Therefore, a program must call a library
  146: function after the program is loaded and running to finish setting up
  147: the library code.  For example, when libcurl is built for SSL
  148: capability via the GNU TLS library, there is an elaborate tree inside
  149: that library that describes the SSL protocol.
  150: 
  151: \fIcurl_global_init(3)\fP is the function that you must call.  This may
  152: allocate resources (e.g. the memory for the GNU TLS tree mentioned above), so
  153: the companion function \fIcurl_global_cleanup(3)\fP releases them.
  154: 
  155: The basic rule for constructing a program that uses libcurl is this: Call
  156: \fIcurl_global_init(3)\fP, with a \fICURL_GLOBAL_ALL\fP argument, immediately
  157: after the program starts, while it is still only one thread and before it uses
  158: libcurl at all.  Call \fIcurl_global_cleanup(3)\fP immediately before the
  159: program exits, when the program is again only one thread and after its last
  160: use of libcurl.
  161: 
  162: You can call both of these multiple times, as long as all calls meet
  163: these requirements and the number of calls to each is the same.
  164: 
  165: It isn't actually required that the functions be called at the beginning
  166: and end of the program -- that's just usually the easiest way to do it.
  167: It \fIis\fP required that the functions be called when no other thread
  168: in the program is running.
  169: 
  170: These global constant functions are \fInot thread safe\fP, so you must
  171: not call them when any other thread in the program is running.  It
  172: isn't good enough that no other thread is using libcurl at the time,
  173: because these functions internally call similar functions of other
  174: libraries, and those functions are similarly thread-unsafe.  You can't
  175: generally know what these libraries are, or whether other threads are
  176: using them.
  177: 
  178: The global constant situation merits special consideration when the
  179: code you are writing to use libcurl is not the main program, but rather
  180: a modular piece of a program, e.g. another library.  As a module,
  181: your code doesn't know about other parts of the program -- it doesn't
  182: know whether they use libcurl or not.  And its code doesn't necessarily
  183: run at the start and end of the whole program.
  184: 
  185: A module like this must have global constant functions of its own, just like
  186: \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP.  The module thus
  187: has control at the beginning and end of the program and has a place to call
  188: the libcurl functions.  Note that if multiple modules in the program use
  189: libcurl, they all will separately call the libcurl functions, and that's OK
  190: because only the first \fIcurl_global_init(3)\fP and the last
  191: \fIcurl_global_cleanup(3)\fP in a program change anything.  (libcurl uses a
  192: reference count in static memory).
  193: 
  194: In a C++ module, it is common to deal with the global constant situation by
  195: defining a special class that represents the global constant environment of
  196: the module.  A program always has exactly one object of the class, in static
  197: storage.  That way, the program automatically calls the constructor of the
  198: object as the program starts up and the destructor as it terminates.  As the
  199: author of this libcurl-using module, you can make the constructor call
  200: \fIcurl_global_init(3)\fP and the destructor call \fIcurl_global_cleanup(3)\fP
  201: and satisfy libcurl's requirements without your user having to think about it.
  202: (Caveat: If you are initializing libcurl from a Windows DLL you should not
  203: initialize it from DllMain or a static initializer because Windows holds the
  204: loader lock during that time and it could cause a deadlock.)
  205: 
  206: \fIcurl_global_init(3)\fP has an argument that tells what particular parts of
  207: the global constant environment to set up.  In order to successfully use any
  208: value except \fICURL_GLOBAL_ALL\fP (which says to set up the whole thing), you
  209: must have specific knowledge of internal workings of libcurl and all other
  210: parts of the program of which it is part.
  211: 
  212: A special part of the global constant environment is the identity of the
  213: memory allocator.  \fIcurl_global_init(3)\fP selects the system default memory
  214: allocator, but you can use \fIcurl_global_init_mem(3)\fP to supply one of your
  215: own.  However, there is no way to use \fIcurl_global_init_mem(3)\fP in a
  216: modular program -- all modules in the program that might use libcurl would
  217: have to agree on one allocator.
  218: 
  219: There is a failsafe in libcurl that makes it usable in simple situations
  220: without you having to worry about the global constant environment at all:
  221: \fIcurl_easy_init(3)\fP sets up the environment itself if it hasn't been done
  222: yet.  The resources it acquires to do so get released by the operating system
  223: automatically when the program exits.
  224: 
  225: This failsafe feature exists mainly for backward compatibility because
  226: there was a time when the global functions didn't exist.  Because it
  227: is sufficient only in the simplest of programs, it is not recommended
  228: for any program to rely on it.