hello world

neo/curl/docs/libcurl/libcurl-multi.3

@@ -0,0 +1,100 @@
+.\" You can view this file with:
+.\" nroff -man [file]
+.\" $Id: libcurl-multi.3,v 1.8 2004/03/15 11:37:38 bagder Exp $
+.\"
+.TH libcurl-multi 3 "13 Oct 2001" "libcurl 7.10.1" "libcurl multi interface"
+.SH NAME
+libcurl-multi \- how to use the multi interface
+.SH DESCRIPTION
+This is an overview on how to use the libcurl multi interface 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 and the \fIlibcurl(3)\fP man page for an overview of
+the libcurl easy interface.
+
+All functions in the multi interface are prefixed with curl_multi.
+.SH "PLEASE NOTICE"
+The multi interface is a rather new member of the libcurl family. It has not
+yet been very widely used. It may still be a few more bugs lurking in there
+than we are used to. That said, it might also just work in every aspect you
+try it. Please report all bugs and oddities you see.
+.SH "OBJECTIVES"
+The multi interface introduces several new abilities that the easy interface
+refuses to offer. They are mainly:
+
+1. Enable a "pull" interface. The application that uses libcurl decides where
+and when to ask libcurl to get/send data.
+
+2. Enable multiple simultaneous transfers in the same thread without making it
+complicated for the application.
+
+3. Enable the application to select() on its own file descriptors and curl's
+file descriptors simultaneous easily.
+.SH "ONE MULTI HANDLE MANY EASY HANDLES"
+To use the multi interface, you must first create a 'multi handle' with
+\fIcurl_multi_init(3)\fP. This handle is then used as input to all further
+curl_multi_* functions.
+
+Each single transfer is built up with an easy handle. You must create them,
+and setup the appropriate options for each easy handle, as outlined in the
+\fIlibcurl(3)\fP man page, using \fIcurl_easy_setopt(3)\fP.
+
+When the easy handle is setup for a transfer, then instead of using
+\fIcurl_easy_perform(3)\fP (as when using the easy interface for transfers),
+you should instead add the easy handle to the multi handle using
+\fIcurl_multi_add_handle(3)\fP. The multi handle is sometimes referred to as a
+\'multi stack\' because of the fact that it may hold a large amount of easy
+handles.
+
+Should you change your mind, the easy handle is again removed from the multi
+stack using \fIcurl_multi_remove_handle(3)\fP. Once removed from the multi
+handle, you can again use other easy interface functions like
+\fIcurl_easy_perform(3)\fP on the handle or whatever you think is necessary.
+
+Adding the easy handle to the multi handle does not start the transfer.
+Remember that one of the main ideas with this interface is to let your
+application drive. You drive the transfers by invoking
+\fIcurl_multi_perform(3)\fP. libcurl will then transfer data if there is
+anything available to transfer. It'll use the callbacks and everything else
+you have setup in the individual easy handles. It'll transfer data on all
+current transfers in the multi stack that are ready to transfer anything. It
+may be all, it may be none.
+
+Your application can acquire knowledge from libcurl when it would like to get
+invoked to transfer data, so that you don't have to busy-loop and call that
+\fIcurl_multi_perform(3)\fP like crazy. \fIcurl_multi_fdset(3)\fP offers an
+interface using which you can extract fd_sets from libcurl to use in select()
+or poll() calls in order to get to know when the transfers in the multi stack
+might need attention. This also makes it very easy for your program to wait
+for input on your own private file descriptors at the same time or perhaps
+timeout every now and then, should you want that.
+
+A little note here about the return codes from the multi functions, and
+especially the \fIcurl_multi_perform(3)\fP: if you receive
+\fICURLM_CALL_MULTI_PERFORM\fP, this basicly means that you should call
+\fIcurl_multi_perform(3)\fP again, before you select() on more actions. You
+don't have to do it immediately, but the return code means that libcurl may
+have more data available to return or that there may be more data to send off
+before it is "satisfied".
+
+\fIcurl_multi_perform(3)\fP stores the number of still running transfers in
+one of its input arguments, and by reading that you can figure out when all
+the transfers in the multi handles are done. 'done' does not mean
+successful. One or more of the transfers may have failed. Tracking when this
+number changes, you know when one or more transfers are done.
+
+To get information about completed transfers, to figure out success or not and
+similar, \fIcurl_multi_info_read(3)\fP should be called. It can return a
+message about a current or previous transfer. Repeated invokes of the function
+get more messages until the message queue is empty. The information you
+receive there includes an easy handle pointer which you may use to identify
+which easy handle the information regards.
+
+When all transfers in the multi stack are done, cleanup the multi handle with
+\fIcurl_multi_cleanup(3)\fP. Be careful and please note that you \fBMUST\fP
+invoke separate \fIcurl_easy_cleanup(3)\fP calls on every single easy handle
+to clean them up properly.
+
+If you want to re-use an easy handle that was added to the multi handle for
+transfer, you must first remove it from the multi stack and then re-add it
+again (possbily after having altered some options at your own choice).