4
<!-- Manpage converted by man2html 3.0.1 -->
8
libcurl - client-side URL transfers
12
<H2>DESCRIPTION</H2><PRE>
13
This is an overview on how to use libcurl in your C pro�
14
grams. There are specific man pages for each function men�
15
tioned in here. There's also the libcurl-the-guide document
16
for a complete tutorial to programming with libcurl.
18
libcurl can also be used directly from within your Java,
19
PHP, Perl, Ruby or Tcl programs as well, look elsewhere for
20
documentation on this!
22
All applications that use libcurl should call
23
<I>curl</I><B>_</B><I>global</I><B>_</B><I>init()</I> exactly once before any libcurl function
24
can be used. After all usage of libcurl is complete, it <B>must</B>
25
call <I>curl</I><B>_</B><I>global</I><B>_</B><I>cleanup()</I>. In between those two calls, you
26
can use libcurl as described below.
28
When using libcurl you init your session and get a handle,
29
which you use as input to the following interface functions
30
you use. Use <I>curl</I><B>_</B><I>easy</I><B>_</B><I>init()</I> to get the handle.
32
You continue by setting all the options you want in the
33
upcoming transfer, most important among them is the URL
34
itself (you can't transfer anything without a specified URL
35
as you may have figured out yourself). You might want to set
36
some callbacks as well that will be called from the library
37
when data is available etc. <I>curl</I><B>_</B><I>easy</I><B>_</B><I>setopt()</I> is there for
40
When all is setup, you tell libcurl to perform the transfer
41
using <I>curl</I><B>_</B><I>easy</I><B>_</B><I>perform()</I>. It will then do the entire oper�
42
ation and won't return until it is done (successfully or
45
After the transfer has been made, you can set new options
46
and make another transfer, or if you're done, cleanup the
47
session by calling <I>curl</I><B>_</B><I>easy</I><B>_</B><I>cleanup()</I>. If you want persis�
48
tant connections, you don't cleanup immediately, but instead
49
run ahead and perform other transfers using the same handle.
50
See the chapter below for Persistant Connections.
52
There is also a series of other helpful functions to use.
57
displays the libcurl version
60
converts a date string to time_t
63
portable environment variable reader
65
<B>curl_easy_getinfo()</B>
66
get information about a performed transfer
69
helps building a HTTP form POST
71
<B>curl_formfree()</B>
72
free a list built with curl_form�
73
parse()/curl_formadd()
75
<B>curl_slist_append()</B>
78
<B>curl_slist_free_all()</B>
79
frees a whole curl_slist
82
portable printf() functions
84
<B>curl_strequal()</B>
85
portable case insensitive string comparisons
90
<H2>LINKING WITH LIBCURL</H2><PRE>
91
Starting with 7.7.2 (on unix-like machines), there's a tool
92
named curl-config that gets installed with the rest of the
93
curl stuff when 'make install' is performed.
95
curl-config is added to make it easier for applications to
96
link with libcurl and developers to learn about libcurl and
99
Run 'curl-config --libs' to get the (additional) linker
100
options you need to link with the particular version of
101
libcurl you've installed.
103
For details, see the curl-config.1 man page.
107
<H2>LIBCURL SYMBOL NAMES</H2><PRE>
108
All public functions in the libcurl interface are prefixed
109
with 'curl_' (with a lowercase c). You can find other func�
110
tions in the library source code, but other prefixes indi�
111
cate the functions are private and may change without fur�
112
ther notice in the next release.
114
Only use documented functions and functionality!
118
<H2>PORTABILITY</H2><PRE>
119
libcurl works <B>exactly</B> the same, on any of the platforms it
120
compiles and builds on.
122
There's only one caution, and that is the win32 platform
123
that may(*) require you to init the winsock stuff before you
124
use the libcurl functions. Details on this are noted on the
125
curl_easy_init() man page.
127
(*) = it appears as if users of the cygwin environment get
128
this done automatically, also libcurl 7.8.1 and later can
133
<H2>THREADS</H2><PRE>
134
Never ever call curl-functions simultaneously using the same
135
handle from several threads. libcurl is thread-safe and can
136
be used in any number of threads, but you must use separate
137
curl handles if you want to use libcurl in more than one
138
thread simultaneously.
142
<H2>PERSISTANT CONNECTIONS</H2><PRE>
143
With libcurl 7.7, persistant connections were added. Persis�
144
tant connections means that libcurl can re-use the same con�
145
nection for several transfers, if the conditions are right.
147
libcurl will *always* attempt to use persistant connections.
148
Whenever you use curl_easy_perform(), libcurl will attempt
149
to use an existing connection to do the transfer, and if
150
none exists it'll open a new one that will be subject for
151
re-use on a possible following call to curl_easy_perform().
153
To allow libcurl to take full advantage of persistant con�
154
nections, you should do as many of your file transfers as
155
possible using the same curl handle. When you call
156
curl_easy_cleanup(), all the possibly open connections held
157
by libcurl will be closed and forgotten.
159
Note that the options set with curl_easy_setopt() will be
160
used in on every repeat curl_easy_perform() call
164
<H2>COMPATIBILITY WITH OLDER LIBCURLS</H2><PRE>
165
Repeated curl_easy_perform() calls on the same handle were
166
not supported in pre-7.7 versions, and caused confusion and
181
Man(1) output converted with
182
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
added
removed
docs/libcurl/libcurl.html
