| .\" 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/c++ programs. There are |
| specific man pages for each function mentioned in here. |
| |
| 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_formparse() |
| helps building a HTTP form POST (deprecated since 7.9 use curl_formadd()!) |
| .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. |
| |