diff options
| -rw-r--r-- | docs/libcurl/curl_multi_socket.3 | 90 |
1 files changed, 49 insertions, 41 deletions
diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index ada5155bd..38fe60013 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -10,7 +10,10 @@ curl_multi_socket \- reads/writes available data CURLMcode curl_multi_socket_action(CURLM * multi_handle, curl_socket_t sockfd, int ev_bitmask, int *running_handles); +.fi +.B "Now deprecated versions:" +.nf CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd, int *running_handles); @@ -20,47 +23,48 @@ CURLMcode curl_multi_socket_all(CURLM *multi_handle, .SH DESCRIPTION Alternative versions of \fIcurl_multi_perform(3)\fP that allows the application to pass in the file descriptor/socket that has been detected to -have \&"action" on it and let libcurl perform. This allows libcurl to not have -to scan through all possible file descriptors to check for action. When the -application has detected action on a socket handled by libcurl, it should call -\fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument set to the -socket with the action. When the events on a socket are known, they can be -passed as an events bitmask \fBev_bitmask\fP by first setting \fBev_bitmask\fP -to 0, and then adding using bitwise OR (|) any combination of events to be -chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the -events on a socket are unknown, pass 0 instead, and libcurl will test the -descriptor internally. - -At return, the int \fBrunning_handles\fP points to will contain the number of -still running easy handles within the multi handle. When this number reaches -zero, all transfers are complete/done. Note that when you call +have \&"action" on it and let libcurl perform. This lets libcurl avoid having +to scan through all possible file descriptors to check for action. + +When the application has detected action on a socket handled by libcurl, it +should call \fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument +set to the socket with the action. When the events on a socket are known, they +can be passed as an events bitmask \fBev_bitmask\fP by first setting +\fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of +events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or +CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and +libcurl will test the descriptor internally. + +At return, the integer \fBrunning_handles\fP points to will contain the number +of still running easy handles within the multi handle. When this number +reaches zero, all transfers are complete/done. Note that when you call \fIcurl_multi_socket_action(3)\fP on a specific socket and the counter decreases by one, it DOES NOT necessarily mean that this exact socket/transfer is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed. -The curl_multi_socket functions inform the application about updates in the -socket (file descriptor) status by doing none, one or multiple calls to the -socket callback function set with the CURLMOPT_SOCKETFUNCTION option to -\fIcurl_multi_setopt(3)\fP. They update the status with changes since the -previous time this function was called. - -Force libcurl to (re-)check all its internal sockets and transfers instead of -just a single one by calling \fBcurl_multi_socket_all(3)\fP. Note that there -should rarely be reasons to use this function! - -Get the timeout time - how long to wait for socket actions at most before -doing the timeout action: call the \fBcurl_multi_socket(3)\fP function with -the \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT, by setting the -\fICURLMOPT_TIMERFUNCTION\fP option with \fIcurl_multi_setopt(3)\fP. You can -also use the \fIcurl_multi_timeout(3)\fP function to poll the value at any -given time, but for an event-based system using the callback is far better -than relying on polling the timeout value. +The \fBcurl_multi_socket_action(3)\fP functions inform the application about +updates in the socket (file descriptor) status by doing none, one or multiple +calls to the socket callback function set with the CURLMOPT_SOCKETFUNCTION +option to \fIcurl_multi_setopt(3)\fP. They update the status with changes +since the previous time the callback was called. + +Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION\fP option with +\fIcurl_multi_setopt(3)\fP. Your application will then get called with +information on how long to wait for socket actions at most before doing the +timeout action: call the \fBcurl_multi_socket_action(3)\fP function with the +\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the +\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but +for an event-based system using the callback is far better than relying on +polling the timeout value. Usage of \fIcurl_multi_socket(3)\fP is deprecated, whereas the function is -equivalent to \fIcurl_multi_socket_action(3)\fP, when \fBev_bitmask\fP is set -to 0. +equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to +0. +Force libcurl to (re-)check all its internal sockets and transfers instead of +just a single one by calling \fBcurl_multi_socket_all(3)\fP. Note that there +should not exist any reasons to use this function! .SH "CALLBACK DETAILS" The socket \fBcallback\fP function uses a prototype like this @@ -107,15 +111,19 @@ The \fIuserp\fP argument is a private pointer you have previously set with .SH "RETURN VALUE" CURLMcode type, general libcurl multi interface error code. -If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you -should call \fIcurl_multi_socket(3)\fP again, before you wait for more actions -on libcurl's sockets. 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". +Legacy: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means +that you should call \fIcurl_multi_socket(3)\fP again, before you wait for +more actions on libcurl's sockets. 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". + +In modern libcurls, \fICURLM_CALL_MULTI_PERFORM\fP or +\fICURLM_CALL_MULTI_SOKCET\fP should not be returned and no application needs +to care about them. -NOTE that this only returns errors etc regarding the whole multi stack. There -might still have occurred problems on individual transfers even when this -function returns OK. +NOTE that the return code is for the whole multi stack. There might still have +occurred problems on individual transfers even when one of these functions +return OK. .SH "TYPICAL USAGE" 1. Create a multi handle |