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