repo/core/curl/files/curl_multi_waitfds.3

.\" generated by cd2nroff 0.1 from curl_multi_waitfds.md
.TH curl_multi_waitfds 3 "2024-07-29" libcurl
.SH NAME
curl_multi_waitfds \- extract file descriptor information from a multi handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
#include <stdlib.h>

CURLMcode curl_multi_waitfds(CURLM *multi,
                             struct curl_waitfd *ufds,
                             unsigned int size,
                             unsigned int *fd_count);
.fi
.SH DESCRIPTION
This function extracts \fIcurl_waitfd\fP structures which are similar to
\fIpoll(2)\fP\(aqs \fIpollfd\fP structure from a given multi_handle.

These structures can be used for polling on multi_handle file descriptors in a
fashion similar to \fIcurl_multi_poll(3)\fP. The \fIcurl_multi_perform(3)\fP
function should be called as soon as one of them is ready to be read from or
written to.

libcurl fills provided \fIufds\fP array up to the \fIsize\fP.
If a number of descriptors used by the multi_handle is greater than the
\fIsize\fP parameter then libcurl returns CURLM_OUT_OF_MEMORY error.

If the \fIfd_count\fP argument is not a null pointer, it points to a variable
that on returns specifies the number of descriptors used by the multi_handle to
be checked for being ready to read or write.

The client code can pass \fIsize\fP equal to zero just to get the number of the
descriptors and allocate appropriate storage for them to be used in a
subsequent function call.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
  CURLMcode mc;
  struct curl_waitfd *ufds;

  CURLM *multi = curl_multi_init();

  do {
    /* call curl_multi_perform() */

    /* get the count of file descriptors from the transfers */
    unsigned int fd_count = 0;

    mc = curl_multi_waitfds(multi, NULL, 0, &fd_count);

    if(mc != CURLM_OK) {
      fprintf(stderr, "curl_multi_waitfds() failed, code %d.\\n", mc);
      break;
    }

    if(!fd_count)
      continue; /* no descriptors yet */

    /* Allocate storage for our descriptors.
    * Note that a better approach can be used to minimize allocations and
    * deallocations, if needed, like pre-allocated or grow-only array.
    */
    ufds = (struct curl_waitfd*)malloc(fd_count * sizeof(struct curl_waitfd));

    /* get wait descriptors from the transfers and put them into array. */
    mc = curl_multi_waitfds(multi, ufds, fd_count, NULL);

    if(mc != CURLM_OK) {
      fprintf(stderr, "curl_multi_waitfds() failed, code %d.\\n", mc);
      free(ufds);
      break;
    }

    /* Do polling on descriptors in ufds */

    free(ufds);
  } while (!mc);
}
.fi
.SH AVAILABILITY
Added in curl 8.8.0
.SH RETURN VALUE
\fBCURLMcode\fP type, general libcurl multi interface error code. See
\fIlibcurl\-errors(3)\fP
.SH SEE ALSO
.BR curl_multi_fdset (3),
.BR curl_multi_perform (3),
.BR curl_multi_poll (3),
.BR curl_multi_wait (3)