mirror of
https://github.com/unknownworlds/NS.git
synced 2024-12-18 16:32:07 +00:00
2f9f0c732e
git-svn-id: https://unknownworlds.svn.cloudforge.com/ns1@277 67975925-1194-0748-b3d5-c16f83f1a3a1
178 lines
6.2 KiB
HTML
178 lines
6.2 KiB
HTML
<HTML>
|
|
<BODY>
|
|
<PRE>
|
|
<!-- Manpage converted by man2html 3.0.1 -->
|
|
libcurl - client-side URL transfers
|
|
|
|
|
|
</PRE>
|
|
<H2>DESCRIPTION</H2><PRE>
|
|
This is an overview on how to use libcurl in your C pro-
|
|
grams. There are specific man pages for each function men-
|
|
tioned in here. There's also the libcurl-the-guide docu-
|
|
ment for a complete tutorial to programming with libcurl.
|
|
|
|
There are a dozen custom bindings that bring libcurl
|
|
access to your favourite language. Look elsewhere for doc-
|
|
umentation on those.
|
|
|
|
All applications that use libcurl should call
|
|
<I>curl</I><B>_</B><I>global</I><B>_</B><I>init()</I> exactly once before any libcurl func-
|
|
tion can be used. After all usage of libcurl is complete,
|
|
it <B>must</B> call <I>curl</I><B>_</B><I>global</I><B>_</B><I>cleanup()</I>. In between those two
|
|
calls, you can use libcurl as described below.
|
|
|
|
When using libcurl's "easy" interface you init your ses-
|
|
sion and get a handle, which you use as input to the easy
|
|
interface functions you use. Use <I>curl</I><B>_</B><I>easy</I><B>_</B><I>init()</I> to get
|
|
the handle. There is also the so called "multi" interface,
|
|
try the <I>libcurl-multi(3)</I> man page for an overview of that.
|
|
|
|
You continue by setting all the options you want in the
|
|
upcoming transfer, most important among them is the URL
|
|
itself (you can't transfer anything without a specified
|
|
URL as you may have figured out yourself). You might want
|
|
to set some callbacks as well that will be called from the
|
|
library when data is available etc. <I>curl</I><B>_</B><I>easy</I><B>_</B><I>setopt()</I> is
|
|
there for this.
|
|
|
|
When all is setup, you tell libcurl to perform the trans-
|
|
fer using <I>curl</I><B>_</B><I>easy</I><B>_</B><I>perform()</I>. It will then do the entire
|
|
operation and won't return until it is done (successfully
|
|
or not).
|
|
|
|
After the transfer has been made, you can set new options
|
|
and make another transfer, or if you're done, cleanup the
|
|
session by calling <I>curl</I><B>_</B><I>easy</I><B>_</B><I>cleanup()</I>. If you want per-
|
|
sistant connections, you don't cleanup immediately, but
|
|
instead run ahead and perform other transfers using the
|
|
same handle. See the chapter below for Persistant Connec-
|
|
tions.
|
|
|
|
There is also a series of other helpful functions to use.
|
|
They are:
|
|
|
|
|
|
<B>curl_version()</B>
|
|
displays the libcurl version
|
|
|
|
converts a date string to time_t
|
|
|
|
<B>curl_getenv()</B>
|
|
portable environment variable reader
|
|
|
|
<B>curl_easy_getinfo()</B>
|
|
get information about a performed trans-
|
|
fer
|
|
|
|
<B>curl_formadd()</B>
|
|
helps building a HTTP form POST
|
|
|
|
<B>curl_formfree()</B>
|
|
free a list built with curl_form-
|
|
parse()/curl_formadd()
|
|
|
|
<B>curl_slist_append()</B>
|
|
builds a linked list
|
|
|
|
<B>curl_slist_free_all()</B>
|
|
frees a whole curl_slist
|
|
|
|
<B>curl_mprintf()</B>
|
|
portable printf() functions
|
|
|
|
<B>curl_strequal()</B>
|
|
portable case insensitive string compar-
|
|
isons
|
|
|
|
|
|
|
|
</PRE>
|
|
<H2>LINKING WITH LIBCURL</H2><PRE>
|
|
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.
|
|
|
|
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 link with the particular version of
|
|
libcurl you've installed.
|
|
|
|
For details, see the curl-config.1 man page.
|
|
|
|
|
|
</PRE>
|
|
<H2>LIBCURL SYMBOL NAMES</H2><PRE>
|
|
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 other prefixes
|
|
indicate the functions are private and may change without
|
|
further notice in the next release.
|
|
|
|
libcurl works <B>exactly</B> the same, on any of the platforms it
|
|
compiles and builds on.
|
|
|
|
|
|
</PRE>
|
|
<H2>THREADS</H2><PRE>
|
|
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.
|
|
|
|
|
|
</PRE>
|
|
<H2>PERSISTANT CONNECTIONS</H2><PRE>
|
|
Persistent connections means that libcurl can re-use the
|
|
same connection for several transfers, if the conditions
|
|
are right.
|
|
|
|
libcurl will *always* attempt to use persistent connec-
|
|
tions. Whenever you use curl_easy_perform(), libcurl will
|
|
attempt to use an existing connection to do the transfer,
|
|
and if none exists it'll open a new one that will be sub-
|
|
ject for re-use on a possible following call to
|
|
curl_easy_perform().
|
|
|
|
To allow libcurl to take full advantage of persistent con-
|
|
nections, you should do as many of your file transfers as
|
|
possible using the same curl handle. When you call
|
|
curl_easy_cleanup(), all the possibly open connections
|
|
held by libcurl will be closed and forgotten.
|
|
|
|
Note that the options set with curl_easy_setopt() will be
|
|
used in on every repeat curl_easy_perform() call
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</PRE>
|
|
<HR>
|
|
<ADDRESS>
|
|
Man(1) output converted with
|
|
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
|
|
</ADDRESS>
|
|
</BODY>
|
|
</HTML>
|