| .\" You can view this file with: |
| .\" nroff -man [file] |
| .\" $Id$ |
| .\" |
| .TH libcurl 3 "19 March 2002" "libcurl 7.9.6" "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. |
| |
| There are a dozen custom bindings that bring libcurl access to your favourite |
| language. Look elsewhere for documentation on those. |
| |
| 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's "easy" interface you init your session and get a handle, |
| which you use as input to the easy interface functions you use. Use |
| \fIcurl_easy_init()\fP to get the handle. There is also the so called "multi" |
| interface, try the \fIlibcurl-multi(3)\fP 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. \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" |
| 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. |
| .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" |
| 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 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 persistent 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 |