2002-03-04 13:09:48 +03:00
|
|
|
.\"
|
2002-04-09 10:20:06 +04:00
|
|
|
.TH libcurl 3 "19 March 2002" "libcurl 7.9.6" "libcurl overview"
|
2002-03-04 13:09:48 +03:00
|
|
|
.SH NAME
|
|
|
|
libcurl \- client-side URL transfers
|
|
|
|
.SH DESCRIPTION
|
2008-12-22 16:07:13 +03:00
|
|
|
This is a short overview on how to use libcurl in your C programs. There are
|
2003-08-12 12:46:02 +04:00
|
|
|
specific man pages for each function mentioned in here. There are also the
|
2004-03-15 15:41:24 +03:00
|
|
|
\fIlibcurl-easy(3)\fP man page, the \fIlibcurl-multi(3)\fP man page, the
|
2004-06-21 12:28:10 +04:00
|
|
|
\fIlibcurl-share(3)\fP man page and the \fIlibcurl-tutorial(3)\fP man page for
|
|
|
|
in-depth understanding on how to program with libcurl.
|
2002-03-04 13:09:48 +03:00
|
|
|
|
2006-06-21 21:34:29 +04:00
|
|
|
There are more than thirty custom bindings available that bring libcurl access
|
|
|
|
to your favourite language. Look elsewhere for documentation on those.
|
2002-03-04 13:09:48 +03:00
|
|
|
|
2006-01-16 02:55:53 +03:00
|
|
|
libcurl has a global constant environment that you must set up and
|
|
|
|
maintain while using libcurl. This essentially means you call
|
|
|
|
\fIcurl_global_init(3)\fP at the start of your program and
|
|
|
|
\fIcurl_global_cleanup(3)\fP at the end. See GLOBAL CONSTANTS below
|
|
|
|
for details.
|
2002-03-04 13:09:48 +03:00
|
|
|
|
2003-08-12 12:46:02 +04:00
|
|
|
To transfer files, you always set up an "easy handle" using
|
2004-03-25 00:40:45 +03:00
|
|
|
\fIcurl_easy_init(3)\fP, but when you want the file(s) transferred you have
|
|
|
|
the option of using the "easy" interface, or the "multi" interface.
|
2002-03-04 13:09:48 +03:00
|
|
|
|
2003-08-12 12:46:02 +04:00
|
|
|
The easy interface is a synchronous interface with which you call
|
2004-03-15 15:41:24 +03:00
|
|
|
\fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is
|
2008-12-22 16:07:13 +03:00
|
|
|
completed, the function returns and you can continue. More details are found in
|
2004-03-15 15:41:24 +03:00
|
|
|
the \fIlibcurl-easy(3)\fP man page.
|
2002-03-04 13:09:48 +03:00
|
|
|
|
2003-08-12 12:46:02 +04:00
|
|
|
The multi interface on the other hand is an asynchronous interface, that you
|
2004-03-25 00:40:45 +03:00
|
|
|
call and that performs only a little piece of the transfer on each invoke. It
|
2003-08-12 12:46:02 +04:00
|
|
|
is perfect if you want to do things while the transfer is in progress, or
|
|
|
|
similar. The multi interface allows you to select() on libcurl action, and
|
2008-12-22 16:07:13 +03:00
|
|
|
even to easily download multiple files simultaneously using a single thread. See further details in the \fIlibcurl-multi(3)\fP man page.
|
2002-03-04 13:09:48 +03:00
|
|
|
|
2003-08-12 12:46:02 +04:00
|
|
|
You can have multiple easy handles share certain data, even if they are used
|
|
|
|
in different threads. This magic is setup using the share interface, as
|
2004-03-15 15:41:24 +03:00
|
|
|
described in the \fIlibcurl-share(3)\fP man page.
|
2002-03-04 13:09:48 +03:00
|
|
|
|
2004-05-05 10:11:57 +04:00
|
|
|
There is also a series of other helpful functions to use, including these:
|
2002-03-04 13:09:48 +03:00
|
|
|
.RS
|
2004-05-05 10:11:57 +04:00
|
|
|
.IP curl_version_info()
|
|
|
|
gets detailed libcurl (and other used libraries) version info
|
|
|
|
.IP curl_getdate()
|
2002-03-04 13:09:48 +03:00
|
|
|
converts a date string to time_t
|
2004-05-05 10:11:57 +04:00
|
|
|
.IP curl_easy_getinfo()
|
2002-03-04 13:09:48 +03:00
|
|
|
get information about a performed transfer
|
2004-05-05 10:11:57 +04:00
|
|
|
.IP curl_formadd()
|
2004-03-25 00:40:45 +03:00
|
|
|
helps building an HTTP form POST
|
2004-05-05 10:11:57 +04:00
|
|
|
.IP curl_formfree()
|
2004-03-15 14:56:07 +03:00
|
|
|
free a list built with \fIcurl_formadd(3)\fP
|
2004-05-05 10:11:57 +04:00
|
|
|
.IP curl_slist_append()
|
2002-03-04 13:09:48 +03:00
|
|
|
builds a linked list
|
2004-05-05 10:11:57 +04:00
|
|
|
.IP curl_slist_free_all()
|
2002-03-04 13:09:48 +03:00
|
|
|
frees a whole curl_slist
|
|
|
|
.RE
|
|
|
|
|
|
|
|
.SH "LINKING WITH LIBCURL"
|
2002-04-09 10:20:06 +04:00
|
|
|
On unix-like machines, there's a tool named curl-config that gets installed
|
|
|
|
with the rest of the curl stuff when 'make install' is performed.
|
2002-03-04 13:09:48 +03:00
|
|
|
|
|
|
|
curl-config is added to make it easier for applications to link with libcurl
|
|
|
|
and developers to learn about libcurl and how to use it.
|
|
|
|
|
|
|
|
Run 'curl-config --libs' to get the (additional) linker options you need to
|
2004-05-05 10:11:57 +04:00
|
|
|
link with the particular version of libcurl you've installed. See the
|
|
|
|
\fIcurl-config(1)\fP man page for further details.
|
|
|
|
|
|
|
|
Unix-like operating system that ship libcurl as part of their distributions
|
|
|
|
often don't provide the curl-config tool, but simply install the library and
|
|
|
|
headers in the common path for this purpose.
|
2002-03-04 13:09:48 +03:00
|
|
|
|
|
|
|
.SH "LIBCURL SYMBOL NAMES"
|
|
|
|
All public functions in the libcurl interface are prefixed with 'curl_' (with
|
|
|
|
a lowercase c). You can find other functions in the library source code, but
|
2004-05-05 10:11:57 +04:00
|
|
|
other prefixes indicate that the functions are private and may change without
|
2002-03-04 13:09:48 +03:00
|
|
|
further notice in the next release.
|
|
|
|
|
|
|
|
Only use documented functions and functionality!
|
|
|
|
.SH "PORTABILITY"
|
|
|
|
libcurl works
|
|
|
|
.B exactly
|
|
|
|
the same, on any of the platforms it compiles and builds on.
|
|
|
|
.SH "THREADS"
|
|
|
|
Never ever call curl-functions simultaneously using the same handle from
|
|
|
|
several threads. libcurl is thread-safe and can be used in any number of
|
|
|
|
threads, but you must use separate curl handles if you want to use libcurl in
|
|
|
|
more than one thread simultaneously.
|
2006-01-16 02:55:53 +03:00
|
|
|
|
|
|
|
The global environment functions are not thread-safe. See GLOBAL CONSTANTS
|
|
|
|
below for details.
|
|
|
|
|
2004-03-15 15:41:24 +03:00
|
|
|
.SH "PERSISTENT CONNECTIONS"
|
2002-04-09 10:20:06 +04:00
|
|
|
Persistent connections means that libcurl can re-use the same connection for
|
|
|
|
several transfers, if the conditions are right.
|
2002-03-04 13:09:48 +03:00
|
|
|
|
2004-03-15 15:41:24 +03:00
|
|
|
libcurl will \fBalways\fP attempt to use persistent connections. Whenever you
|
|
|
|
use \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP, libcurl will
|
2004-03-15 14:56:07 +03:00
|
|
|
attempt to use an existing connection to do the transfer, and if none exists
|
|
|
|
it'll open a new one that will be subject for re-use on a possible following
|
|
|
|
call to \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP.
|
2002-03-04 13:09:48 +03:00
|
|
|
|
2002-04-09 10:20:06 +04:00
|
|
|
To allow libcurl to take full advantage of persistent connections, you should
|
|
|
|
do as many of your file transfers as possible using the same curl handle. When
|
2004-03-15 14:56:07 +03:00
|
|
|
you call \fIcurl_easy_cleanup(3)\fP, all the possibly open connections held by
|
2002-04-09 10:20:06 +04:00
|
|
|
libcurl will be closed and forgotten.
|
2002-03-04 13:09:48 +03:00
|
|
|
|
2008-12-22 16:07:13 +03:00
|
|
|
Note that the options set with \fIcurl_easy_setopt(3)\fP will be used on
|
2004-03-15 14:56:07 +03:00
|
|
|
every repeated \fIcurl_easy_perform(3)\fP call.
|
2006-01-16 02:55:53 +03:00
|
|
|
|
|
|
|
.SH "GLOBAL CONSTANTS"
|
|
|
|
There are a variety of constants that libcurl uses, mainly through its
|
|
|
|
internal use of other libraries, which are too complicated for the
|
|
|
|
library loader to set up. Therefore, a program must call a library
|
|
|
|
function after the program is loaded and running to finish setting up
|
|
|
|
the library code. For example, when libcurl is built for SSL
|
|
|
|
capability via the GNU TLS library, there is an elaborate tree inside
|
|
|
|
that library that describes the SSL protocol.
|
|
|
|
|
|
|
|
\fIcurl_global_init()\fP is the function that you must call. This may
|
|
|
|
allocate resources (e.g. the memory for the GNU TLS tree mentioned
|
|
|
|
above), so the companion function \fIcurl_global_cleanup()\fP releases
|
|
|
|
them.
|
|
|
|
|
|
|
|
The basic rule for constructing a program that uses libcurl is this:
|
|
|
|
Call \fIcurl_global_init()\fP, with a \fICURL_GLOBAL_ALL\fP argument,
|
|
|
|
immediately after the program starts, while it is still only one
|
|
|
|
thread and before it uses libcurl at all. Call
|
|
|
|
\fIcurl_global_cleanup()\fP immediately before the program exits, when
|
|
|
|
the program is again only one thread and after its last use of
|
|
|
|
libcurl.
|
|
|
|
|
|
|
|
You can call both of these multiple times, as long as all calls meet
|
|
|
|
these requirements and the number of calls to each is the same.
|
|
|
|
|
|
|
|
It isn't actually required that the functions be called at the beginning
|
|
|
|
and end of the program -- that's just usually the easiest way to do it.
|
|
|
|
It \fIis\fP required that the functions be called when no other thread
|
|
|
|
in the program is running.
|
|
|
|
|
|
|
|
These global constant functions are \fInot thread safe\fP, so you must
|
|
|
|
not call them when any other thread in the program is running. It
|
|
|
|
isn't good enough that no other thread is using libcurl at the time,
|
|
|
|
because these functions internally call similar functions of other
|
|
|
|
libraries, and those functions are similarly thread-unsafe. You can't
|
|
|
|
generally know what these libraries are, or whether other threads are
|
|
|
|
using them.
|
|
|
|
|
|
|
|
The global constant situation merits special consideration when the
|
|
|
|
code you are writing to use libcurl is not the main program, but rather
|
|
|
|
a modular piece of a program, e.g. another library. As a module,
|
|
|
|
your code doesn't know about other parts of the program -- it doesn't
|
|
|
|
know whether they use libcurl or not. And its code doesn't necessarily
|
|
|
|
run at the start and end of the whole program.
|
|
|
|
|
|
|
|
A module like this must have global constant functions of its own,
|
|
|
|
just like \fIcurl_global_init()\fP and \fIcurl_global_cleanup()\fP.
|
|
|
|
The module thus has control at the beginning and end of the program
|
|
|
|
and has a place to call the libcurl functions. Note that if multiple
|
|
|
|
modules in the program use libcurl, they all will separately call the
|
|
|
|
libcurl functions, and that's OK because only the first
|
|
|
|
\fIcurl_global_init()\fP and the last \fIcurl_global_cleanup()\fP in a
|
2008-12-22 16:07:13 +03:00
|
|
|
program change anything. (libcurl uses a reference count in static
|
2006-01-16 02:55:53 +03:00
|
|
|
memory).
|
|
|
|
|
|
|
|
In a C++ module, it is common to deal with the global constant
|
|
|
|
situation by defining a special class that represents the global
|
|
|
|
constant environment of the module. A program always has exactly one
|
|
|
|
object of the class, in static storage. That way, the program
|
|
|
|
automatically calls the constructor of the object as the program
|
|
|
|
starts up and the destructor as it terminates. As the author of this
|
|
|
|
libcurl-using module, you can make the constructor call
|
|
|
|
\fIcurl_global_init()\fP and the destructor call
|
|
|
|
\fIcurl_global_cleanup()\fP and satisfy libcurl's requirements without
|
|
|
|
your user having to think about it.
|
|
|
|
|
|
|
|
\fIcurl_global_init()\fP has an argument that tells what particular
|
|
|
|
parts of the global constant environment to set up. In order to
|
|
|
|
successfully use any value except \fICURL_GLOBAL_ALL\fP (which says to
|
|
|
|
set up the whole thing), you must have specific knowledge of internal
|
|
|
|
workings of libcurl and all other parts of the program of which it is
|
|
|
|
part.
|
|
|
|
|
|
|
|
A special part of the global constant environment is the identity of
|
|
|
|
the memory allocator. \fIcurl_global_init()\fP selects the system
|
|
|
|
default memory allocator, but you can use \fIcurl_global_init_mem()\fP
|
|
|
|
to supply one of your own. However, there is no way to use
|
|
|
|
\fIcurl_global_init_mem()\fP in a modular program -- all modules in
|
|
|
|
the program that might use libcurl would have to agree on one
|
|
|
|
allocator.
|
|
|
|
|
|
|
|
There is a failsafe in libcurl that makes it usable in simple
|
|
|
|
situations without you having to worry about the global constant
|
|
|
|
environment at all: \fIcurl_easy_init()\fP sets up the environment
|
|
|
|
itself if it hasn't been done yet. The resources it acquires to do so
|
|
|
|
get released by the operating system automatically when the program
|
|
|
|
exits.
|
|
|
|
|
|
|
|
This failsafe feature exists mainly for backward compatibility because
|
|
|
|
there was a time when the global functions didn't exist. Because it
|
|
|
|
is sufficient only in the simplest of programs, it is not recommended
|
|
|
|
for any program to rely on it.
|