1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_multi_socket_action
5Section: 3
6Source: libcurl
7See-also:
8  - curl_multi_cleanup (3)
9  - curl_multi_fdset (3)
10  - curl_multi_info_read (3)
11  - curl_multi_init (3)
12  - the hiperfifo.c example
13Protocol:
14  - All
15Added-in: 7.15.4
16---
17
18# NAME
19
20curl_multi_socket_action - read/write available data given an action
21
22# SYNOPSIS
23
24~~~c
25#include <curl/curl.h>
26
27CURLMcode curl_multi_socket_action(CURLM *multi_handle,
28                                   curl_socket_t sockfd,
29                                   int ev_bitmask,
30                                   int *running_handles);
31~~~
32
33# DESCRIPTION
34
35When the application has detected action on a socket handled by libcurl, it
36should call curl_multi_socket_action(3) with the **sockfd** argument
37set to the socket with the action. When the events on a socket are known, they
38can be passed as an events bitmask **ev_bitmask** by first setting
39**ev_bitmask** to 0, and then adding using bitwise OR (|) any combination of
40events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or
41CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and
42libcurl tests the descriptor internally. It is also permissible to pass
43CURL_SOCKET_TIMEOUT to the **sockfd** parameter in order to initiate the
44whole process or when a timeout occurs.
45
46At return, **running_handles** points to the number of running easy handles
47within the multi handle. When this number reaches zero, all transfers are
48complete/done. When you call curl_multi_socket_action(3) on a specific
49socket and the counter decreases by one, it DOES NOT necessarily mean that
50this exact socket/transfer is the one that completed. Use
51curl_multi_info_read(3) to figure out which easy handle that completed.
52
53The curl_multi_socket_action(3) function informs the application about
54updates in the socket (file descriptor) status by doing none, one, or multiple
55calls to the socket callback function set with the
56CURLMOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They
57update the status with changes since the previous time the callback was
58called.
59
60Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option
61with curl_multi_setopt(3). Your application then gets called with
62information on how long to wait for socket actions at most before doing the
63timeout action: call the curl_multi_socket_action(3) function with the
64**sockfd** argument set to CURL_SOCKET_TIMEOUT. You can also use the
65curl_multi_timeout(3) function to poll the value at any given time, but
66for an event-based system using the callback is far better than relying on
67polling the timeout value.
68
69When this function returns error, the state of all transfers are uncertain and
70they cannot be continued. curl_multi_socket_action(3) should not be
71called again on the same multi handle after an error has been returned, unless
72first removing all the handles and adding new ones.
73
74# TYPICAL USAGE
75
761. Create a multi handle
77
782. Set the socket callback with CURLMOPT_SOCKETFUNCTION(3)
79
803. Set the timeout callback with CURLMOPT_TIMERFUNCTION(3), to get to
81know what timeout value to use when waiting for socket activities.
82
834. Add easy handles with curl_multi_add_handle()
84
855. Provide some means to manage the sockets libcurl is using, so you can check
86them for activity. This can be done through your application code, or by way
87of an external library such as libevent or glib.
88
896. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...)
90to kickstart everything. To get one or more callbacks called.
91
927. Wait for activity on any of libcurl's sockets, use the timeout value your
93callback has been told.
94
958, When activity is detected, call curl_multi_socket_action() for the
96socket(s) that got action. If no activity is detected and the timeout expires,
97call curl_multi_socket_action(3) with *CURL_SOCKET_TIMEOUT*.
98
99# %PROTOCOLS%
100
101# EXAMPLE
102
103~~~c
104int main(void)
105{
106  /* the event-library gets told when there activity on the socket 'fd',
107     which we translate to a call to curl_multi_socket_action() */
108  int running;
109  CURLM *multi; /* the stack we work with */
110  int fd; /* the descriptor that had action */
111  int bitmask; /* what activity that happened */
112  CURLMcode mc = curl_multi_socket_action(multi, fd, bitmask, &running);
113  if(mc)
114    printf("error: %s\n", curl_multi_strerror(mc));
115}
116~~~
117
118# %AVAILABILITY%
119
120# RETURN VALUE
121
122CURLMcode type, general libcurl multi interface error code. See
123libcurl-errors(3)
124