diff options
Diffstat (limited to 'plugins/FTPFileYM/curl/docs/libcurl/libcurl-multi.3')
| -rw-r--r-- | plugins/FTPFileYM/curl/docs/libcurl/libcurl-multi.3 | 151 |
1 files changed, 0 insertions, 151 deletions
diff --git a/plugins/FTPFileYM/curl/docs/libcurl/libcurl-multi.3 b/plugins/FTPFileYM/curl/docs/libcurl/libcurl-multi.3 deleted file mode 100644 index 2af0299619..0000000000 --- a/plugins/FTPFileYM/curl/docs/libcurl/libcurl-multi.3 +++ /dev/null @@ -1,151 +0,0 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * Project ___| | | | _ \| | -.\" * / __| | | | |_) | | -.\" * | (__| |_| | _ <| |___ -.\" * \___|\___/|_| \_\_____| -.\" * -.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. -.\" * -.\" * This software is licensed as described in the file COPYING, which -.\" * you should have received as part of this distribution. The terms -.\" * are also available at http://curl.haxx.se/docs/copyright.html. -.\" * -.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell -.\" * copies of the Software, and permit persons to whom the Software is -.\" * furnished to do so, under the terms of the COPYING file. -.\" * -.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY -.\" * KIND, either express or implied. -.\" * -.\" ************************************************************************** -.\" -.TH libcurl-multi 3 "3 Feb 2007" "libcurl 7.16.0" "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 \fIlibcurl-tutorial(3)\fP man page for a complete -tutorial to programming with libcurl and the \fIlibcurl-easy(3)\fP man page -for an overview of the libcurl easy interface. - -All functions in the multi interface are prefixed with curl_multi. -.SH "OBJECTIVES" -The multi interface offers several abilities that the easy interface doesn't. -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 wait for action 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. - -\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 a single transfer is completed, the easy handle is still left added to -the multi stack. You need to first remove the easy handle with -\fIcurl_multi_remove_handle(3)\fP and then close it with -\fIcurl_easy_cleanup(3)\fP, or possibly set new options to it and add it again -with \fIcurl_multi_add_handle(3)\fP to start another transfer. - -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 (possibly after having altered some options at your own choice). -.SH "MULTI_SOCKET" -\fIcurl_multi_socket_action(3)\fP function offers a way for applications to -not only avoid being forced to use select(), but it also offers a much more -high-performance API that will make a significant difference for applications -using large numbers of simultaneous connections. - -\fIcurl_multi_socket_action(3)\fP is then used instead of -\fIcurl_multi_perform(3)\fP. - -When using this API, you add easy handles to the multi handle just as with the -normal multi interface. Then you also set two callbacks with the -CURLMOPT_SOCKETFUNCTION and CURLMOPT_TIMERFUNCTION options to -\fIcurl_multi_setopt(3)\fP. - -The API is then designed to inform your application about which sockets -libcurl is currently using and for what activities (read and/or write) on -those sockets your application is expected to wait for. - -Your application must then make sure to receive all sockets informed about in -the CURLMOPT_SOCKETFUNCTION callback and make sure it reacts on the given -activity on them. When a socket has the given activity, you call -\fIcurl_multi_socket_action(3)\fP specifying which socket and action there -are. - -The CURLMOPT_TIMERFUNCTION callback is called to set a timeout. When that -timeout expires, your application should call the -\fIcurl_multi_socket_action(3)\fP function saying it was due to a timeout. -.SH "BLOCKING" -A few areas in the code are still using blocking code, even when used from the -multi interface. While we certainly want and intend for these to get fixed in -the future, you should be aware of the following current restrictions: - -.nf - - Name resolves unless the c-ares or threaded-resolver backends are used - - NSS SSL connections - - HTTP proxy CONNECT operations - - SOCKS proxy handshakes - - file:// transfers - - TELNET transfers -.fi |