updated to match current reality

CURLMcode curl_multi_socket_action(CURLM * multi_handle, 

CURLMcode curl_multi_socket_action(CURLM * multi_handle, 

                                   curl_socket_t sockfd, int ev_bitmask,

                                   curl_socket_t sockfd, int ev_bitmask,

                                   int *running_handles);

                                   int *running_handles);

.fi

.B "Now deprecated versions:"

.nf

CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd,

CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd,

                            int *running_handles);

                            int *running_handles);

.SH DESCRIPTION

.SH DESCRIPTION

Alternative versions of \fIcurl_multi_perform(3)\fP that allows the

Alternative versions of \fIcurl_multi_perform(3)\fP that allows the

application to pass in the file descriptor/socket that has been detected to

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

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

to scan through all possible file descriptors to check for action.

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

When the application has detected action on a socket handled by libcurl, it

socket with the action. When the events on a socket are known, they can be

should call \fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument

passed as an events bitmask \fBev_bitmask\fP by first setting \fBev_bitmask\fP

set to the socket with the action. When the events on a socket are known, they

to 0, and then adding using bitwise OR (|) any combination of events to be

can be passed as an events bitmask \fBev_bitmask\fP by first setting

chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the

\fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of

events on a socket are unknown, pass 0 instead, and libcurl will test the

events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or

descriptor internally.

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

At return, the integer \fBrunning_handles\fP points to will contain the number

zero, all transfers are complete/done. Note that when you call

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

\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

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

is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out

which easy handle that completed.

which easy handle that completed.

The curl_multi_socket functions inform the application about updates in the

The \fBcurl_multi_socket_action(3)\fP functions inform the application about

socket (file descriptor) status by doing none, one or multiple calls to the

updates in the socket (file descriptor) status by doing none, one or multiple

socket callback function set with the CURLMOPT_SOCKETFUNCTION option to

calls to the socket callback function set with the CURLMOPT_SOCKETFUNCTION

\fIcurl_multi_setopt(3)\fP. They update the status with changes since the

option to \fIcurl_multi_setopt(3)\fP. They update the status with changes

previous time this function was called.

since the previous time the callback was called.

Force libcurl to (re-)check all its internal sockets and transfers instead of

Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION\fP option with

just a single one by calling \fBcurl_multi_socket_all(3)\fP. Note that there

\fIcurl_multi_setopt(3)\fP. Your application will then get called with

should rarely be reasons to use this function!

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

Get the timeout time - how long to wait for socket actions at most before

\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the

doing the timeout action: call the \fBcurl_multi_socket(3)\fP function with

\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but

the \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT, by setting the

for an event-based system using the callback is far better than relying on

\fICURLMOPT_TIMERFUNCTION\fP option with \fIcurl_multi_setopt(3)\fP. You can

polling the timeout value.

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

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 

equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to

to 0.

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"

.SH "CALLBACK DETAILS"

The socket \fBcallback\fP function uses a prototype like this

The socket \fBcallback\fP function uses a prototype like this

.SH "RETURN VALUE"

.SH "RETURN VALUE"

CURLMcode type, general libcurl multi interface error code.

CURLMcode type, general libcurl multi interface error code.

If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you

Legacy: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means

should call \fIcurl_multi_socket(3)\fP again, before you wait for more actions

that you should call \fIcurl_multi_socket(3)\fP again, before you wait for

on libcurl's sockets. You don't have to do it immediately, but the return code

more actions on libcurl's sockets. You don't have to do it immediately, but

means that libcurl may have more data available to return or that there may be

the return code means that libcurl may have more data available to return or

more data to send off before it is "satisfied".

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

NOTE that the return code is for the whole multi stack. There might still have

might still have occurred problems on individual transfers even when this

occurred problems on individual transfers even when one of these functions

function returns OK.

return OK.

.SH "TYPICAL USAGE"

.SH "TYPICAL USAGE"

1. Create a multi handle

1. Create a multi handle