1curl_multi_socket_action(3)     libcurl Manual     curl_multi_socket_action(3)
2
3
4

NAME

6       curl_multi_socket_action - reads/writes available data given an action
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLMcode curl_multi_socket_action(CURLM * multi_handle,
12                                          curl_socket_t sockfd,
13                                          int ev_bitmask,
14                                          int *running_handles);
15

DESCRIPTION

17       When  the  application  has  detected  action  on  a  socket handled by
18       libcurl, it should call  curl_multi_socket_action(3)  with  the  sockfd
19       argument set to the socket with the action. When the events on a socket
20       are known, they can be passed as an events bitmask ev_bitmask by  first
21       setting  ev_bitmask to 0, and then adding using bitwise OR (|) any com‐
22       bination of events to be chosen from CURL_CSELECT_IN,  CURL_CSELECT_OUT
23       or  CURL_CSELECT_ERR.  When  the events on a socket are unknown, pass 0
24       instead, and libcurl will test the descriptor internally.  It  is  also
25       permissible  to  pass  CURL_SOCKET_TIMEOUT  to  the sockfd parameter in
26       order to initiate the whole process or when a timeout occurs.
27
28       At return, running_handles points to the number of running easy handles
29       within  the  multi handle. When this number reaches zero, all transfers
30       are complete/done. When you call curl_multi_socket_action(3) on a  spe‐
31       cific  socket and the counter decreases by one, it DOES NOT necessarily
32       mean that this exact socket/transfer is the  one  that  completed.  Use
33       curl_multi_info_read(3) to figure out which easy handle that completed.
34
35       The  curl_multi_socket_action(3) functions inform the application about
36       updates in the socket (file descriptor) status by doing none,  one,  or
37       multiple  calls  to  the  socket  callback  function set with the CURL‐
38       MOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They update  the
39       status with changes since the previous time the callback was called.
40
41       Get  the  timeout  time by setting the CURLMOPT_TIMERFUNCTION(3) option
42       with curl_multi_setopt(3). Your application will then get  called  with
43       information on how long to wait for socket actions at most before doing
44       the timeout action: call the curl_multi_socket_action(3) function  with
45       the  sockfd  argument  set to CURL_SOCKET_TIMEOUT. You can also use the
46       curl_multi_timeout(3) function to poll the value at any given time, but
47       for an event-based system using the callback is far better than relying
48       on polling the timeout value.
49

CALLBACK DETAILS

51       The socket callback function uses a prototype like this
52
53         int curl_socket_callback(CURL *easy,      /* easy handle */
54                                  curl_socket_t s, /* socket */
55                                  int action,      /* see values below */
56                                  void *userp,    /* private callback pointer */
57                                  void *socketp); /* private socket pointer,
58                                                     NULL if not
59                                                     previously assigned with
60                                                     curl_multi_assign(3) */
61
62       The callback MUST return 0.
63
64       The easy argument is a pointer to the easy handle that deals with  this
65       particular  socket.  Note  that  a  single handle may work with several
66       sockets simultaneously.
67
68       The s argument is the actual socket value as you  use  it  within  your
69       system.
70
71       The action argument to the callback has one of five values:
72
73              CURL_POLL_NONE (0)
74                     register, not interested in readiness (yet)
75
76              CURL_POLL_IN (1)
77                     register, interested in read readiness
78
79              CURL_POLL_OUT (2)
80                     register, interested in write readiness
81
82              CURL_POLL_INOUT (3)
83                     register, interested in both read and write readiness
84
85              CURL_POLL_REMOVE (4)
86                     unregister
87
88       The  socketp argument is a private pointer you have previously set with
89       curl_multi_assign(3) to be associated with the s socket. If no  pointer
90       has  been  set, socketp will be NULL. This argument is of course a ser‐
91       vice to applications that want to keep certain data or structs that are
92       strictly associated to the given socket.
93
94       The  userp  argument  is a private pointer you have previously set with
95       curl_multi_setopt(3) and the CURLMOPT_SOCKETDATA(3) option.
96

RETURN VALUE

98       CURLMcode type, general libcurl multi interface error code.
99
100       Before version 7.20.0: If you  receive  CURLM_CALL_MULTI_PERFORM,  this
101       basically  means that you should call curl_multi_socket_action(3) again
102       before you wait for more actions on libcurl's sockets. You  don't  have
103       to  do  it immediately, but the return code means that libcurl may have
104       more data available to return or that there may be more  data  to  send
105       off before it is "satisfied".
106
107       The return code from this function is for the whole multi stack.  Prob‐
108       lems still might have occurred on individual transfers even when one of
109       these functions return OK.
110

TYPICAL USAGE

112       1. Create a multi handle
113
114       2. Set the socket callback with CURLMOPT_SOCKETFUNCTION(3)
115
116       3.  Set  the timeout callback with CURLMOPT_TIMERFUNCTION(3), to get to
117       know what timeout value to use when waiting for socket activities.
118
119       4. Add easy handles with curl_multi_add_handle()
120
121       5. Provide some means to manage the sockets libcurl is  using,  so  you
122       can  check them for activity. This can be done through your application
123       code, or by way of an external library such as libevent or glib.
124
125       6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...)   to
126       kickstart everything. To get one or more callbacks called.
127
128       7. Wait for activity on any of libcurl's sockets, use the timeout value
129       your callback has been told.
130
131       8, When activity is detected, call curl_multi_socket_action()  for  the
132       socket(s)  that  got action. If no activity is detected and the timeout
133       expires, call curl_multi_socket_action(3) with CURL_SOCKET_TIMEOUT.
134

AVAILABILITY

136       This function was added in libcurl 7.15.4, and is deemed  stable  since
137       7.16.0.
138

SEE ALSO

140       curl_multi_cleanup(3),     curl_multi_init(3),     curl_multi_fdset(3),
141       curl_multi_info_read(3), the hiperfifo.c example
142
143
144
145libcurl 7.61.1                   June 30, 2018     curl_multi_socket_action(3)
Impressum