| .\" 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 are also the |
| \fIlibcurl-easy(3)\fP man page, the \fIlibcurl-multi(3)\fP man page, the |
| \fIlibcurl-share(3)\fP man page and the \fIlibcurl-the-guide\fP document for |
| further reading on how to do programming with libcurl. |
| |
| There exist more than 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(3)\fP |
| exactly once before any libcurl function can be used. After all usage of |
| libcurl is complete, it \fBmust\fP call \fIcurl_global_cleanup(3)\fP. In |
| between those two calls, you can use libcurl as described below. |
| |
| To transfer files, you always set up an "easy handle" using |
| \fIcurl_easy_init(3)\fP, but when you want the file(s) transferred you have |
| the option of using the "easy" interface, or the "multi" interface. |
| |
| The easy interface is a synchronous interface with which you call |
| \fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is |
| completed, the function return and you can continue. More details are found in |
| the \fIlibcurl-easy(3)\fP man page. |
| |
| The multi interface on the other hand is an asynchronous interface, that you |
| call and that performs only a little piece of the transfer on each invoke. It |
| is perfect if you want to do things while the transfer is in progress, or |
| similar. The multi interface allows you to select() on libcurl action, and |
| even to easily download multiple files simultaneously using a single thread. See further deails in the \fIlibcurl-multi(3)\fP man page. |
| |
| You can have multiple easy handles share certain data, even if they are used |
| in different threads. This magic is setup using the share interface, as |
| described in the \fIlibcurl-share(3)\fP man page. |
| |
| There is also a series of other helpful functions to use, including these: |
| .RS |
| .IP curl_version_info() |
| gets detailed libcurl (and other used libraries) version info |
| .IP curl_getdate() |
| converts a date string to time_t |
| .IP curl_easy_getinfo() |
| get information about a performed transfer |
| .IP curl_formadd() |
| helps building an HTTP form POST |
| .IP curl_formfree() |
| free a list built with \fIcurl_formadd(3)\fP |
| .IP curl_slist_append() |
| builds a linked list |
| .IP curl_slist_free_all() |
| frees a whole curl_slist |
| .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. See the |
| \fIcurl-config(1)\fP man page for further details. |
| |
| Unix-like operating system that ship libcurl as part of their distributions |
| often don't provide the curl-config tool, but simply install the library and |
| headers in the common path for this purpose. |
| |
| .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 that 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 "PERSISTENT CONNECTIONS" |
| Persistent connections means that libcurl can re-use the same connection for |
| several transfers, if the conditions are right. |
| |
| libcurl will \fBalways\fP attempt to use persistent connections. Whenever you |
| use \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP, 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 \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. |
| |
| 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 \fIcurl_easy_cleanup(3)\fP, all the possibly open connections held by |
| libcurl will be closed and forgotten. |
| |
| Note that the options set with \fIcurl_easy_setopt(3)\fP will be used in on |
| every repeated \fIcurl_easy_perform(3)\fP call. |