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