• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 return 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. In this case, *fd_count* receives a number greater
54than or equal to the number of descriptors.
55
56# %PROTOCOLS%
57
58# EXAMPLE
59
60~~~c
61#include <stdlib.h>
62
63int main(void)
64{
65  CURLMcode mc;
66  struct curl_waitfd *ufds;
67
68  CURLM *multi = curl_multi_init();
69
70  do {
71    /* call curl_multi_perform() */
72
73    /* get the count of file descriptors from the transfers */
74    unsigned int fd_count = 0;
75
76    mc = curl_multi_waitfds(multi, NULL, 0, &fd_count);
77
78    if(mc != CURLM_OK) {
79      fprintf(stderr, "curl_multi_waitfds() failed, code %d.\n", mc);
80      break;
81    }
82
83    if(!fd_count)
84      continue; /* no descriptors yet */
85
86    /* allocate storage for our descriptors */
87    ufds = malloc(fd_count * sizeof(struct curl_waitfd));
88
89    /* get wait descriptors from the transfers and put them into array. */
90    mc = curl_multi_waitfds(multi, ufds, fd_count, &fd_count);
91
92    if(mc != CURLM_OK) {
93      fprintf(stderr, "curl_multi_waitfds() failed, code %d.\n", mc);
94      free(ufds);
95      break;
96    }
97
98    /* Do polling on descriptors in ufds */
99
100    free(ufds);
101  } while(!mc);
102}
103~~~
104
105# %AVAILABILITY%
106
107# RETURN VALUE
108
109This function returns a CURLMcode indicating success or error.
110
111CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
112libcurl-errors(3).
113