.\" *
.\" **************************************************************************
.\"
-.TH libcurl-tutorial 3 "19 Sep 2014" "libcurl" "libcurl programming"
+.TH libcurl-tutorial 3 "4 Mar 2009" "libcurl" "libcurl programming"
.SH NAME
libcurl-tutorial \- libcurl programming tutorial
.SH "Objective"
.SH "Building"
There are many different ways to build C programs. This chapter will assume a
-Unix style build process. If you use a different build system, you can still
+UNIX-style build process. If you use a different build system, you can still
read this to get general information that may apply to your environment as
well.
.IP "Compiling the Program"
struct, your program can figure out exactly what the currently running libcurl
supports.
-.SH "Two Interfaces"
-libcurl first introduced the so called easy interface. All operations in the
-easy interface are prefixed with 'curl_easy'. The easy interface lets you do
-single transfers with a synchronous and blocking function call.
-
-libcurl also offers another interface that allows multiple simultaneous
-transfers in a single thread, the so called multi interface. More about that
-interface is detailed in a separate chapter further down. You still need to
-understand the easy interface first, so please continue reading for better
-understanding.
.SH "Handle the Easy libcurl"
+libcurl first introduced the so called easy interface. All operations in the
+easy interface are prefixed with 'curl_easy'.
+
+Recent libcurl versions also offer the multi interface. More about that
+interface, what it is targeted for and how to use it is detailed in a separate
+chapter further down. You still need to understand the easy interface first,
+so please continue reading for better understanding.
+
To use the easy interface, you must first create yourself an easy handle. You
need one handle for each easy session you want to perform. Basically, you
should use one handle for every thread you plan to use for transferring. You
You set properties and options for this handle using
\fIcurl_easy_setopt(3)\fP. They control how the subsequent transfer or
transfers will be made. Options remain set in the handle until set again to
-something different. They are sticky. Multiple requests using the same handle
-will use the same options.
-
-If you at any point would like to blank all previously set options for a
-single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also
-make a clone of an easy handle (with all its set options) using
-\fIcurl_easy_duphandle(3)\fP.
+something different. Alas, multiple requests using the same handle will use
+the same options.
Many of the options you set in libcurl are "strings", pointers to data
terminated with a zero byte. When you set strings with
-\fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they don't need
-to be kept around in your application after being set[4].
+\fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they don't
+need to be kept around in your application after being set[4].
One of the most basic properties to set in the handle is the URL. You set your
preferred URL to transfer with \fICURLOPT_URL(3)\fP in a manner similar to:
libcurl is completely thread safe, except for two issues: signals and SSL/TLS
handlers. Signals are used for timing out name resolves (during DNS lookup) -
-when built without using either the c-ares or threaded resolver backends.
+when built without c-ares support and not on Windows.
If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are
then of course using the underlying SSL library multi-threaded and those libs
GnuTLS
- http://gnutls.org/manual/html_node/Thread-safety.html
+ http://www.gnu.org/software/gnutls/manual/html_node/Multi_002dthreaded-applications.html
NSS
curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "myname:thesecret");
-There's a long time Unix "standard" way of storing FTP user names and
+There's a long time UNIX "standard" way of storing ftp user names and
passwords, namely in the $HOME/.netrc file. The file should be made private
so that only the user may read it (see also the "Security Considerations"
chapter), as it might contain the password in plain text. libcurl has the
password in clear-text in the HTTP request, base64-encoded. This is insecure.
At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM,
-Negotiate (SPNEGO). You can tell libcurl which one to use
+Negotiate, GSS-Negotiate and SPNEGO. You can tell libcurl which one to use
with \fICURLOPT_HTTPAUTH(3)\fP as in:
curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
Basic uses base64 encoded passwords fool you. They may not look readable at a
first glance, but they very easily "deciphered" by anyone within seconds.
-To avoid this problem, use an authentication mechanism or other protocol that
-doesn't let snoopers see your password: Digest, CRAM-MD5, Kerberos, SPNEGO or
-NTLM authentication, HTTPS, FTPS, SCP and SFTP are a few examples.
+To avoid this problem, use HTTP authentication methods or other protocols that
+don't let snoopers see your password: HTTP with Digest, NTLM or GSS
+authentication, HTTPS, FTPS, SCP, SFTP and FTP-Kerberos are a few examples.
.IP "Redirects"
The \fICURLOPT_FOLLOWLOCATION(3)\fP option automatically follows HTTP
can just edit out the sensitive data or just search/replace your true
information with faked data.
-.SH "The multi Interface"
+.SH "Multiple Transfers Using the multi Interface"
+
The easy interface as described in detail in this document is a synchronous
interface that transfers one file at a time and doesn't return until it is
done.
The multi interface, on the other hand, allows your program to transfer
-multiple files in both directions at the same time, without forcing you to use
-multiple threads. The name might make it seem that the multi interface is for
-multi-threaded programs, but the truth is almost the reverse. The multi
-interface allows a single-threaded application to perform the same kinds of
-multiple, simultaneous transfers that multi-threaded programs can perform. It
-allows many of the benefits of multi-threaded transfers without the complexity
-of managing and synchronizing many threads.
-
-To complicate matters somewhat more, there are even two versions of the multi
-interface. The event based one, also called multi_socket and the "normal one"
-designed for using with select(). See the libcurl-multi.3 man page for details
-on the multi_socket event based API, this description here is for the select()
-oriented one.
+multiple files in both directions at the same time, without forcing you
+to use multiple threads. The name might make it seem that the multi
+interface is for multi-threaded programs, but the truth is almost the
+reverse. The multi interface can allow a single-threaded application
+to perform the same kinds of multiple, simultaneous transfers that
+multi-threaded programs can perform. It allows many of the benefits
+of multi-threaded transfers without the complexity of managing and
+synchronizing many threads.
To use this interface, you are better off if you first understand the basics
of how to use the easy interface. The multi interface is simply a way to make
multiple transfers at the same time by adding up multiple easy handles into
a "multi stack".
-You create the easy handles you want, one for each concurrent transfer, and
-you set all the options just like you learned above, and then you create a
-multi handle with \fIcurl_multi_init(3)\fP and add all those easy handles to
-that multi handle with \fIcurl_multi_add_handle(3)\fP.
+You create the easy handles you want and you set all the options just like you
+have been told above, and then you create a multi handle with
+\fIcurl_multi_init(3)\fP and add all those easy handles to that multi handle
+with \fIcurl_multi_add_handle(3)\fP.
When you've added the handles you have for the moment (you can still add new
ones at any time), you start the transfers by calling
\fIcurl_multi_perform(3)\fP.
-\fIcurl_multi_perform(3)\fP is asynchronous. It will only perform what can be
-done now and then return back control to your program. It is designed to never
-block. You need to keep calling the function until all transfers are
-completed.
+\fIcurl_multi_perform(3)\fP is asynchronous. It will only execute as little as
+possible and then return back control to your program. It is designed to never
+block.
The best usage of this interface is when you do a select() on all possible
file descriptors or sockets to know when to call libcurl again. This also
action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do
what it wants to do. Take note that libcurl does also feature some time-out
code so we advise you to never use very long timeouts on select() before you
-call \fIcurl_multi_perform(3)\fP again. \fIcurl_multi_timeout(3)\fP is
-provided to help you get a suitable timeout period.
-
-Another precaution you should use: always call \fIcurl_multi_fdset(3)\fP
-immediately before the select() call since the current set of file descriptors
-may change in any curl function invoke.
+call \fIcurl_multi_perform(3)\fP, which thus should be called unconditionally
+every now and then even if none of its file descriptors have signaled
+ready. Another precaution you should use: always call
+\fIcurl_multi_fdset(3)\fP immediately before the select() call since the
+current set of file descriptors may change when calling a curl function.
If you want to stop the transfer of one of the easy handles in the stack, you
can use \fIcurl_multi_remove_handle(3)\fP to remove individual easy
DLL. However, you can still do this on Windows if you link with a static
library.
.IP "[3]"
-The curl-config tool is generated at build-time (on Unix-like systems) and
+The curl-config tool is generated at build-time (on UNIX-like systems) and
should be installed with the 'make install' or similar instruction that
installs the library, header files, man pages etc.
.IP "[4]"
This behavior was different in versions before 7.17.0, where strings had to
remain valid past the end of the \fIcurl_easy_setopt(3)\fP call.
-.SH "SEE ALSO"
-.BR libcurl-errors "(3), " libcurl-multi "(3), " libcurl-easy "(3) "
projects / platform / upstream / curl.git / blobdiff