xref: /curl/docs/libcurl/curl_multi_waitfds.md (revision 187b23b0) 
1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_multi_waitfds
5Section: 3
6Source: libcurl
7See-also:
8  - curl_multi_perform (3)
9  - curl_multi_poll (3)
10  - curl_multi_wait (3)
11  - curl_multi_fdset (3)
12Protocol:
13  - All
14---
15
16# NAME
17
18curl_multi_waitfds - extracts file descriptor information from a multi handle
19
20# SYNOPSIS
21
22~~~c
23#include <curl/curl.h>
24#include <stdlib.h>
25
26CURLMcode curl_multi_waitfds(CURLM *multi,
27                             struct curl_waitfd *ufds,
28                             unsigned int size,
29                             unsigned int *fd_count);
30~~~
31
32# DESCRIPTION
33
34This function extracts *curl_waitfd* structures which are similar to
35*poll(2)*'s *pollfd* structure from a given multi_handle.
36
37These structures can be used for polling on multi_handle file descriptors in a
38fashion similar to curl_multi_poll(3). The curl_multi_perform(3)
39function should be called as soon as one of them is ready to be read from or
40written to.
41
42libcurl fills provided *ufds* array up to the *size*.
43If a number of descriptors used by the multi_handle is greater than the
44*size* parameter then libcurl returns CURLM_OUT_OF_MEMORY error.
45
46If the *fd_count* argument is not a null pointer, it points to a variable
47that on returns specifies the number of descriptors used by the multi_handle to
48be checked for being ready to read or write.
49
50The client code can pass *size* equal to zero just to get the number of the
51descriptors and allocate appropriate storage for them to be used in a
52subsequent function call.
53
54# EXAMPLE
55
56~~~c
57int main(void)
58{
59  CURLMcode mc;
60  struct curl_waitfd *ufds;
61
62  CURLM *multi = curl_multi_init();
63
64  do {
65    /* call curl_multi_perform() */
66
67    /* get the count of file descriptors from the transfers */
68    unsigned int fd_count = 0;
69
70    mc = curl_multi_waitfds(multi, NULL, 0, &fd_count);
71
72    if(mc != CURLM_OK) {
73      fprintf(stderr, "curl_multi_waitfds() failed, code %d.\n", mc);
74      break;
75    }
76
77    if(!fd_count)
78      continue; /* no descriptors yet */
79
80    /* Allocate storage for our descriptors.
81    * Note that a better approach can be used to minimize allocations and
82    * deallocations, if needed, like pre-allocated or grow-only array.
83    */
84    ufds = (struct curl_waitfd*)malloc(fd_count * sizeof(struct curl_waitfd));
85
86    /* get wait descriptors from the transfers and put them into array. */
87    mc = curl_multi_waitfds(multi, ufds, fd_count, NULL);
88
89    if(mc != CURLM_OK) {
90      fprintf(stderr, "curl_multi_waitfds() failed, code %d.\n", mc);
91      free(ufds);
92      break;
93    }
94
95    /* Do polling on descriptors in ufds */
96
97    free(ufds);
98  } while (!mc);
99}
100~~~
101
102# AVAILABILITY
103
104Added in 8.8.0
105
106# RETURN VALUE
107
108**CURLMcode** type, general libcurl multi interface error code. See
109libcurl-errors(3)
110