- _ _ _ _
- | (_) |__ ___ _ _ _ __| |
- | | | '_ \ / __| | | | '__| |
- | | | |_) | (__| |_| | | | |
- |_|_|_.__/ \___|\__,_|_| |_|
+This document has been replaced with the libcurl.3 man page.
- How To Use Libcurl In Your C/C++ Program
-
- [ libcurl can be used directly from within your Java, PHP, Perl, Ruby or Tcl
- programs as well, look elsewhere for documentation on this ]
-
- The interface is meant to be very simple for applictions/programmers, hence
- the name "easy". We have therefore minimized the number of entries.
-
-The Easy Interface
-
- When using the easy interface, you init your session and get a handle, which
- you use as input to the following interface functions you use. Use
- curl_easy_init() 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. curl_easy_setopt() is there for this.
-
- When all is setup, you tell libcurl to perform the transfer using
- curl_easy_perform(). It will then do the entire operation and won't return
- until it is done or failed.
-
- After the transfer has been made, you cleanup the session with
- curl_easy_cleanup() and libcurl is entirely off the hook! If you want
- persistant connections, you don't cleanup immediately, but instead run ahead
- and perform other transfers. See the chapter below for Persistant
- Connections.
-
- While the above mentioned four functions are the main functions to use in the
- easy interface, there is a series of other helpful functions to use. They
- are:
-
- curl_version() - displays the libcurl version
- curl_getdate() - converts a date string to time_t
- curl_getenv() - portable environment variable reader
- curl_easy_getinfo() - get information about a performed transfer
- curl_formparse() - helps building a HTTP form POST
- curl_formfree() - free a list built with curl_formparse()
- curl_slist_append() - builds a linked list
- curl_slist_free_all() - frees a whole curl_slist
-
- For details on these, read the separate man pages.
-
-Linking with libcurl
-
- Staring 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.
-
-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!
-
-Portability
-
- libcurl works *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.
-
-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.
-
-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
-
-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 defined behaviour.
+You'll find HTML versions of the the latest man pages as a link on this page:
+ http://curl.haxx.se/libcurl/c/
projects / platform / upstream / curl.git / commitdiff