1libcurl(3)                     libcurl overview                     libcurl(3)
2
3
4

NAME

6       libcurl - client-side URL transfers
7

DESCRIPTION

9       This  is  a  short  overview  on how to use libcurl in your C programs.
10       There are specific man pages for each function mentioned in  here.  See
11       libcurl-easy(3), libcurl-multi(3), libcurl-share(3), libcurl-url(3) and
12       libcurl-tutorial(3) for in-depth understanding on how to  program  with
13       libcurl.
14
15       There are many bindings available that bring libcurl access to your fa‐
16       vorite language. Look elsewhere for documentation on those.
17
18       libcurl has a global constant environment that  you  must  set  up  and
19       maintain   while   using  libcurl.  This  essentially  means  you  call
20       curl_global_init(3)   at   the    start    of    your    program    and
21       curl_global_cleanup(3)  at  the end. See GLOBAL CONSTANTS below for de‐
22       tails.
23
24       If libcurl was compiled with support for  multiple  SSL  backends,  the
25       function curl_global_sslset(3) can be called before curl_global_init(3)
26       to select the active SSL backend.
27
28       To transfer files, you create an "easy handle" using  curl_easy_init(3)
29       for  a  single  individual transfer (in either direction). You then set
30       your desired set of options in that  handle  with  curl_easy_setopt(3).
31       Options  you  set  with curl_easy_setopt(3) stick. They will be used on
32       every repeated use of this handle until you either change  the  option,
33       or you reset them all with curl_easy_reset(3).
34
35       To  actually  transfer data you have the option of using the "easy" in‐
36       terface, or the "multi" interface.
37
38       The easy interface is a  synchronous  interface  with  which  you  call
39       curl_easy_perform(3)  and  let it perform the transfer. When it is com‐
40       pleted, the function returns and you can  continue.  More  details  are
41       found in the libcurl-easy(3) man page.
42
43       The  multi  interface  on  the other hand is an asynchronous interface,
44       that you call and that performs only a little piece of the transfer  on
45       each  invoke. It is perfect if you want to do things while the transfer
46       is in progress, or similar. The multi interface allows you to  select()
47       on  libcurl action, and even to easily download multiple files simulta‐
48       neously using a single thread. See  further  details  in  the  libcurl-
49       multi(3) man page.
50
51       You can have multiple easy handles share certain data, even if they are
52       used in different threads. This magic is setup using the  share  inter‐
53       face, as described in the libcurl-share(3) man page.
54
55       There  is  also  a  series of other helpful functions to use, including
56       these:
57
58              curl_version_info()
59                     gets detailed libcurl (and other used libraries)  version
60                     info
61
62              curl_getdate()
63                     converts a date string to time_t
64
65              curl_easy_getinfo()
66                     get information about a performed transfer
67
68              curl_formadd()
69                     helps building an HTTP form POST
70
71              curl_formfree()
72                     free a list built with curl_formadd(3)
73
74              curl_slist_append()
75                     builds a linked list
76
77              curl_slist_free_all()
78                     frees a whole curl_slist
79
80              curl_url_set()
81                     parses a URL
82
83

LINKING WITH LIBCURL

85       On  unix-like  machines, there's a tool named curl-config that gets in‐
86       stalled with the rest of the curl stuff when  'make  install'  is  per‐
87       formed.
88
89       curl-config  is  added  to make it easier for applications to link with
90       libcurl and developers to learn about libcurl and how to use it.
91
92       Run 'curl-config --libs' to get the  (additional)  linker  options  you
93       need to link with the particular version of libcurl you have installed.
94       See the curl-config(1) man page for further details.
95
96       Unix-like operating system that ship libcurl as part of their distribu‐
97       tions often do not provide the curl-config tool, but simply install the
98       library and headers in the common path for this purpose.
99
100       Many Linux and similar systems use pkg-config to provide build and link
101       options about libraries and libcurl supports that as well.
102

LIBCURL SYMBOL NAMES

104       All public functions in the libcurl interface are prefixed with 'curl_'
105       (with a lowercase c). You can  find  other  functions  in  the  library
106       source code, but other prefixes indicate that the functions are private
107       and may change without further notice in the next release.
108
109       Only use documented functions and functionality!
110

PORTABILITY

112       libcurl works exactly the same, on any of the platforms it compiles and
113       builds on.
114

THREADS

116       libcurl  is  thread  safe  but  there  are  a  few exceptions. Refer to
117       libcurl-thread(3) for more information.
118
119

PERSISTENT CONNECTIONS

121       Persistent connections means that libcurl can re-use the  same  connec‐
122       tion for several transfers, if the conditions are right.
123
124       libcurl will always attempt to use persistent connections. Whenever you
125       use curl_easy_perform(3) or curl_multi_perform(3) etc, libcurl will at‐
126       tempt to use an existing connection to do the transfer, and if none ex‐
127       ists it will open a new one that will be subject for re-use on a possi‐
128       ble following call to curl_easy_perform(3) or curl_multi_perform(3).
129
130       To  allow libcurl to take full advantage of persistent connections, you
131       should do as many of your file transfers as  possible  using  the  same
132       handle.
133
134       If  you  use the easy interface, and you call curl_easy_cleanup(3), all
135       the possibly open connections held by libcurl will be closed  and  for‐
136       gotten.
137
138       When you have created a multi handle and are using the multi interface,
139       the connection pool is instead kept in the multi handle so closing  and
140       creating new easy handles to do transfers will not affect them. Instead
141       all added easy handles can take advantage of the single shared pool.
142

GLOBAL CONSTANTS

144       There are a variety of constants that libcurl uses, mainly through  its
145       internal  use of other libraries, which are too complicated for the li‐
146       brary loader to set up. Therefore, a program must call a library  func‐
147       tion  after  the program is loaded and running to finish setting up the
148       library code. For example, when libcurl is built for SSL capability via
149       the  GNU  TLS  library,  there is an elaborate tree inside that library
150       that describes the SSL protocol.
151
152       curl_global_init(3) is the function that you must call. This may  allo‐
153       cate  resources (e.g. the memory for the GNU TLS tree mentioned above),
154       so the companion function curl_global_cleanup(3) releases them.
155
156       The global constant functions are thread-safe since libcurl  7.84.0  if
157       curl_version_info(3)  has  the  CURL_VERSION_THREADSAFE feature bit set
158       (most platforms). Read libcurl-thread(3) for thread safety guidelines.
159
160       If the global constant functions are not thread safe, then you must not
161       call  them  when  any other thread in the program is running. It is not
162       good enough that no other thread is using libcurl at the time,  because
163       these  functions  internally call similar functions of other libraries,
164       and those functions are similarly thread-unsafe. You  cannot  generally
165       know what these libraries are, or whether other threads are using them.
166
167       If  the  global  constant functions are not thread safe, then the basic
168       rule for constructing  a  program  that  uses  libcurl  is  this:  Call
169       curl_global_init(3), with a CURL_GLOBAL_ALL argument, immediately after
170       the program starts, while it is still only one  thread  and  before  it
171       uses libcurl at all. Call curl_global_cleanup(3) immediately before the
172       program exits, when the program is again only one thread and after  its
173       last use of libcurl.
174
175       It  is not actually required that the functions be called at the begin‐
176       ning and end of the program -- that is just usually the easiest way  to
177       do it.
178
179       You  can  call  both of these multiple times, as long as all calls meet
180       these requirements and the number of calls to each is the same.
181
182       The global constant situation merits  special  consideration  when  the
183       code you are writing to use libcurl is not the main program, but rather
184       a modular piece of a program, e.g. another library. As a  module,  your
185       code does not know about other parts of the program -- it does not know
186       whether they use libcurl or not. And its code does not necessarily  run
187       at the start and end of the whole program.
188
189       A module like this must have global constant functions of its own, just
190       like curl_global_init(3) and curl_global_cleanup(3).  The  module  thus
191       has  control at the beginning and end of the program and has a place to
192       call the libcurl functions. If multiple  modules  in  the  program  use
193       libcurl,  they all will separately call the libcurl functions, and that
194       is  OK  because  only  the  first  curl_global_init(3)  and  the   last
195       curl_global_cleanup(3)  in  a  program change anything. (libcurl uses a
196       reference count in static memory).
197
198       In a C++ module, it is common to deal with the global  constant  situa‐
199       tion  by  defining  a special class that represents the global constant
200       environment of the module. A program always has exactly one  object  of
201       the class, in static storage. That way, the program automatically calls
202       the constructor of the object as the program starts up and the destruc‐
203       tor  as  it terminates. As the author of this libcurl-using module, you
204       can make the constructor call curl_global_init(3)  and  the  destructor
205       call  curl_global_cleanup(3) and satisfy libcurl's requirements without
206       your user having to think about it.  (Caveat: If you  are  initializing
207       libcurl from a Windows DLL you should not initialize it from DllMain or
208       a static initializer because Windows holds the loader lock during  that
209       time and it could cause a deadlock.)
210
211       curl_global_init(3) has an argument that tells what particular parts of
212       the global constant environment to set up. In order to successfully use
213       any  value  except  CURL_GLOBAL_ALL  (which  says  to  set up the whole
214       thing), you must  have  specific  knowledge  of  internal  workings  of
215       libcurl and all other parts of the program of which it is part.
216
217       A  special  part  of the global constant environment is the identity of
218       the memory allocator. curl_global_init(3) selects  the  system  default
219       memory allocator, but you can use curl_global_init_mem(3) to supply one
220       of your own. However, there is no way to use curl_global_init_mem(3) in
221       a  modular program -- all modules in the program that might use libcurl
222       would have to agree on one allocator.
223
224       There is a failsafe in libcurl that makes it usable  in  simple  situa‐
225       tions without you having to worry about the global constant environment
226       at all: curl_easy_init(3) sets up the environment itself if it has  not
227       been  done  yet. The resources it acquires to do so get released by the
228       operating system automatically when the program exits.
229
230       This failsafe feature exists mainly for backward compatibility  because
231       there was a time when the global functions did not exist. Because it is
232       sufficient only in the simplest of programs, it is not recommended  for
233       any program to rely on it.
234
235
236
237libcurl 8.0.1                  January 02, 2023                     libcurl(3)
Impressum