133 lines
5.1 KiB
Groff
133 lines
5.1 KiB
Groff
.\" You can view this file with:
|
|
.\" nroff -man [file]
|
|
.\" $Id$
|
|
.\"
|
|
.TH libcurl 5 "14 August 2001" "libcurl 7.8.1" "libcurl overview"
|
|
.SH NAME
|
|
libcurl \- client-side URL transfers
|
|
.SH DESCRIPTION
|
|
This is an overview on how to use libcurl in your C programs. There are
|
|
specific man pages for each function mentioned in here. There's also the
|
|
libcurl-the-guide document for a complete tutorial to programming with
|
|
libcurl.
|
|
|
|
libcurl can also be used directly from within your Java, PHP, Perl, Ruby or
|
|
Tcl programs as well, look elsewhere for documentation on this!
|
|
|
|
All applications that use libcurl should call \fIcurl_global_init()\fP exactly
|
|
once before any libcurl function can be used. After all usage of libcurl is
|
|
complete, it \fBmust\fP call \fIcurl_global_cleanup()\fP. In between those two
|
|
calls, you can use libcurl as described below.
|
|
|
|
When using libcurl you init your session and get a handle, which you use as
|
|
input to the following interface functions you use. Use \fIcurl_easy_init()\fP
|
|
to get the handle.
|
|
|
|
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. \fIcurl_easy_setopt()\fP is there for this.
|
|
|
|
When all is setup, you tell libcurl to perform the transfer using
|
|
\fIcurl_easy_perform()\fP. 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
|
|
\fIcurl_easy_cleanup()\fP. If you want persistant connections, you don't
|
|
cleanup immediately, but instead run ahead and perform other transfers using
|
|
the same handle. See the chapter below for Persistant Connections.
|
|
|
|
There is also a series of other helpful functions to use. They are:
|
|
|
|
.RS
|
|
.TP 10
|
|
.B curl_version()
|
|
displays the libcurl version
|
|
.TP
|
|
.B curl_getdate()
|
|
converts a date string to time_t
|
|
.TP
|
|
.B curl_getenv()
|
|
portable environment variable reader
|
|
.TP
|
|
.B curl_easy_getinfo()
|
|
get information about a performed transfer
|
|
.TP
|
|
.B curl_formadd()
|
|
helps building a HTTP form POST
|
|
.TP
|
|
.B curl_formfree()
|
|
free a list built with curl_formparse()/curl_formadd()
|
|
.TP
|
|
.B curl_slist_append()
|
|
builds a linked list
|
|
.TP
|
|
.B curl_slist_free_all()
|
|
frees a whole curl_slist
|
|
.TP
|
|
.B curl_mprintf()
|
|
portable printf() functions
|
|
.TP
|
|
.B curl_strequal()
|
|
portable case insensitive string comparisons
|
|
.RE
|
|
|
|
.SH "LINKING WITH LIBCURL"
|
|
Starting with 7.7.2 (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.
|
|
.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
|
|
other prefixes indicate the functions are private and may change without
|
|
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.
|
|
|
|
There's only one caution, and that is the win32 platform that may(*) require
|
|
you to init the winsock stuff before you use the libcurl functions. Details on
|
|
this are noted on the curl_easy_init() man page.
|
|
|
|
(*) = it appears as if users of the cygwin environment get this done
|
|
automatically, also libcurl 7.8.1 and later can handle this for you.
|
|
.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.
|
|
.SH "PERSISTANT CONNECTIONS"
|
|
With libcurl 7.7, persistant connections were added. Persistant connections
|
|
means that libcurl can re-use the same connection for several transfers, if
|
|
the conditions are right.
|
|
|
|
libcurl will *always* attempt to use persistant connections. 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 subject
|
|
for re-use on a possible following call to curl_easy_perform().
|
|
|
|
To allow libcurl to take full advantage of persistant connections, 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
|
|
.SH "COMPATIBILITY WITH OLDER LIBCURLS"
|
|
Repeated curl_easy_perform() calls on the same handle were not supported in
|
|
pre-7.7 versions, and caused confusion and undefined behaviour.
|
|
|