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