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