third-party libs

third-party/curl-7.21.4/docs/libcurl/curl_multi_perform.3

@@ -0,0 +1,53 @@
+.\"
+.TH curl_multi_perform 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual"
+.SH NAME
+curl_multi_perform - reads/writes available data from each easy handle
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles);
+.ad
+.SH DESCRIPTION
+When the app thinks there's data available for the multi_handle, it should
+call this function to read/write whatever there is to read or write right
+now. curl_multi_perform() returns as soon as the reads/writes are done. This
+function does not require that there actually is any data available for
+reading or that data can be written, it can be called just in case. It will
+write the number of handles that still transfer data in the second argument's
+integer-pointer.
+
+When you call curl_multi_perform() and the amount of \fIrunning_handles\fP is
+changed from the previous call (or is less than the amount of easy handles
+you've added to the multi handle), you know that there is one or more
+transfers less "running". You can then call \fIcurl_multi_info_read(3)\fP to
+get information about each individual completed transfer, and that returned
+info includes CURLcode and more. If an added handle fails very quickly, it may
+never be counted as a running_handle.
+
+When \fIrunning_handles\fP is set to zero (0) on the return of this function,
+there is no longer any transfers in progress.
+.SH "RETURN VALUE"
+CURLMcode type, general libcurl multi interface error code.
+
+Before version 7.20.0: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this
+basically means that you should call \fIcurl_multi_perform\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". Do note that
+\fIcurl_multi_perform(3)\fP will return \fICURLM_CALL_MULTI_PERFORM\fP only
+when it wants to be called again \fBimmediately\fP. When things are fine and
+there is nothing immediate it wants done, it'll return \fICURLM_OK\fP and you
+need to wait for \&"action" and then call this function again.
+
+This function only returns errors etc regarding the whole multi stack.
+Problems still might have occurred on individual transfers even when this
+function returns \fICURLM_OK\fP.
+.SH "TYPICAL USAGE"
+Most applications will use \fIcurl_multi_fdset(3)\fP to get the multi_handle's
+file descriptors, then it'll wait for action on them using \fBselect(3)\fP and
+as soon as one or more of them are ready, \fIcurl_multi_perform(3)\fP gets
+called.
+.SH "SEE ALSO"
+.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
+.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "
+.BR libcurl-errors "(3)"