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
16       favourite 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've 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 don't 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'll open a new one that will be subject for re-use on a possible
128       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've  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
149       via 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 basic rule for constructing a program that uses  libcurl  is  this:
157       Call  curl_global_init(3), with a CURL_GLOBAL_ALL argument, immediately
158       after the program starts, while it is still only one thread and  before
159       it uses libcurl at all.  Call curl_global_cleanup(3) immediately before
160       the program exits, when the program is again only one thread and  after
161       its last use of libcurl.
162
163       You  can  call  both of these multiple times, as long as all calls meet
164       these requirements and the number of calls to each is the same.
165
166       It isn't actually required that the functions be called at  the  begin‐
167       ning  and  end of the program -- that's just usually the easiest way to
168       do it.  It is required that the  functions  be  called  when  no  other
169       thread in the program is running.
170
171       These  global  constant  functions are not thread safe, so you must not
172       call them when any other thread in the program is  running.   It  isn't
173       good  enough that no other thread is using libcurl at the time, because
174       these functions internally call similar functions of  other  libraries,
175       and  those  functions are similarly thread-unsafe.  You can't generally
176       know what these libraries are, or whether other threads are 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,  your
181       code  doesn't  know about other parts of the program -- it doesn't know
182       whether they use libcurl or not.  And its code doesn't necessarily  run
183       at the start and end of the whole program.
184
185       A module like this must have global constant functions of its own, just
186       like curl_global_init(3) and curl_global_cleanup(3).  The  module  thus
187       has  control at the beginning and end of the program and has a place to
188       call the libcurl functions.  Note that if multiple modules in the  pro‐
189       gram  use libcurl, they all will separately call the libcurl functions,
190       and that's OK because only the first curl_global_init(3) and  the  last
191       curl_global_cleanup(3)  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  situa‐
195       tion  by  defining  a special class that represents the global constant
196       environment of the module.  A program always has exactly one object  of
197       the  class,  in  static  storage.   That way, the program automatically
198       calls the constructor of the object as the program starts  up  and  the
199       destructor  as it terminates.  As the author of this libcurl-using mod‐
200       ule, you can make the constructor call curl_global_init(3) and the  de‐
201       structor call curl_global_cleanup(3) and satisfy libcurl's requirements
202       without your user having to think about it.  (Caveat: If you  are  ini‐
203       tializing  libcurl from a Windows DLL you should not initialize it from
204       DllMain or a static initializer because Windows holds the  loader  lock
205       during that time and it could cause a deadlock.)
206
207       curl_global_init(3) has an argument that tells what particular parts of
208       the global constant environment to set up.  In  order  to  successfully
209       use  any  value  except CURL_GLOBAL_ALL (which says to set up the whole
210       thing), you must  have  specific  knowledge  of  internal  workings  of
211       libcurl and all other parts of the program of which it is part.
212
213       A  special  part  of the global constant environment is the identity of
214       the memory allocator.  curl_global_init(3) selects the  system  default
215       memory allocator, but you can use curl_global_init_mem(3) to supply one
216       of your own.  However, there is no way to  use  curl_global_init_mem(3)
217       in  a  modular  program  --  all  modules in the program that might use
218       libcurl would have to agree on one allocator.
219
220       There is a failsafe in libcurl that makes it usable  in  simple  situa‐
221       tions without you having to worry about the global constant environment
222       at all: curl_easy_init(3) sets up the environment itself if  it  hasn't
223       been  done yet.  The resources it acquires to do so get released by the
224       operating system automatically when the program exits.
225
226       This failsafe feature exists mainly for backward compatibility  because
227       there was a time when the global functions didn't exist.  Because it is
228       sufficient only in the simplest of programs, it is not recommended  for
229       any program to rely on it.
230
231
232
233libcurl 7.79.1                   May 05, 2021                       libcurl(3)
Impressum