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