xref: /curl/docs/libcurl/curl_multi_wait.md (revision 5a488251) 
1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_multi_wait
5Section: 3
6Source: libcurl
7See-also:
8  - curl_multi_fdset (3)
9  - curl_multi_perform (3)
10  - curl_multi_poll (3)
11Protocol:
12  - All
13Added-in: 7.28.0
14---
15
16# NAME
17
18curl_multi_wait - poll on all easy handles in a multi handle
19
20# SYNOPSIS
21
22~~~c
23#include <curl/curl.h>
24
25CURLMcode curl_multi_wait(CURLM *multi_handle,
26                          struct curl_waitfd extra_fds[],
27                          unsigned int extra_nfds,
28                          int timeout_ms,
29                          int *numfds);
30~~~
31
32# DESCRIPTION
33
34curl_multi_wait(3) polls all file descriptors used by the curl easy
35handles contained in the given multi handle set. It blocks until activity is
36detected on at least one of the handles or *timeout_ms* has passed.
37Alternatively, if the multi handle has a pending internal timeout that has a
38shorter expiry time than *timeout_ms*, that shorter time is being used
39instead to make sure timeout accuracy is reasonably kept.
40
41The calling application may pass additional *curl_waitfd* structures which
42are similar to *poll(2)*'s *pollfd* structure to be waited on in the
43same call.
44
45On completion, if *numfds* is non-NULL, it gets populated with the total
46number of file descriptors on which interesting events occurred. This number
47can include both libcurl internal descriptors as well as descriptors provided
48in *extra_fds*.
49
50If no extra file descriptors are provided and libcurl has no file descriptor
51to offer to wait for, this function returns immediately. (Consider using
52curl_multi_poll(3) to avoid this behavior.)
53
54This function is encouraged to be used instead of select(3) when using the
55multi interface to allow applications to easier circumvent the common problem
56with 1024 maximum file descriptors.
57
58# curl_waitfd
59
60~~~c
61struct curl_waitfd {
62  curl_socket_t fd;
63  short events;
64  short revents;
65};
66~~~
67
68## CURL_WAIT_POLLIN
69
70Bit flag to *curl_waitfd.events* indicating the socket should poll on read
71events such as new data received.
72
73## CURL_WAIT_POLLPRI
74
75Bit flag to *curl_waitfd.events* indicating the socket should poll on high
76priority read events such as out of band data.
77
78## CURL_WAIT_POLLOUT
79
80Bit flag to *curl_waitfd.events* indicating the socket should poll on
81write events such as the socket being clear to write without blocking.
82
83# %PROTOCOLS%
84
85# EXAMPLE
86
87~~~c
88int main(void)
89{
90  CURL *easy;
91  CURLM *multi = curl_multi_init();
92  int still_running;
93
94  /* add the individual easy handle */
95  curl_multi_add_handle(multi, easy);
96
97  do {
98    CURLMcode mc;
99    int numfds;
100
101    mc = curl_multi_perform(multi, &still_running);
102
103    if(mc == CURLM_OK) {
104      /* wait for activity, timeout or "nothing" */
105      mc = curl_multi_wait(multi, NULL, 0, 1000, &numfds);
106    }
107
108    if(mc != CURLM_OK) {
109      fprintf(stderr, "curl_multi failed, code %d.\n", mc);
110      break;
111    }
112
113  } while(still_running);
114
115  curl_multi_remove_handle(multi, easy);
116}
117~~~
118
119# %AVAILABILITY%
120
121# RETURN VALUE
122
123CURLMcode type, general libcurl multi interface error code. See
124libcurl-errors(3)
125