curl_multi_waitfds(3)

💅 curl_multi_waitfds — bestie, let's talk

okay so this is a page from the libcurl Library Functions Manual ✨ — yes, that libcurl, the one you already know and love. sit down, grab a strawberry, we're getting into it 🍓

---

🌸 NAME 🌸

curl_multi_waitfds — extract file descriptor info from a multi handle. that's it, that's the vibe. it's giving "tell me what file descriptors your multi handle is working with" 🦋

---

✨ SYNOPSIS ✨

#include <curl/curl.h>
#include <stdlib.h>

CURLMcode curl_multi_waitfds(CURLM *multi,
                             struct curl_waitfd *ufds,
                             unsigned int size,
                             unsigned int *fd_count);

like, four arguments, no drama, main character energy 👑

---

💖 DESCRIPTION 💖

okay so this function extracts curl_waitfd structures from a given multi_handle. and bestie, these structs are literally siblings of poll(2)'s pollfd structure — no cap, same energy 🔥

you can use these structures to poll on the multi_handle file descriptors, in a fashion similar to curl_multi_poll(3). and the moment one of them is ready to be read from or written to, you should call curl_multi_perform(3). like, immediately. don't ghost it 😭

libcurl fills your provided ufds array up to size. but heads up:

if the number of descriptors used by the multi_handle is greater than the size parameter, libcurl returns CURLM_OUT_OF_MEMORY. so don't be stingy with the size, bestie 💀

if the fd_count argument is not a null pointer, it points to a variable that on return specifies the number of descriptors used by the multi_handle to be checked for being ready to read or write. iconic behavior, honestly 🎀

and here's the cute trick: the client code can pass size equal to zero just to get the number of descriptors, then allocate appropriate storage for them to be used in a subsequent function call. in this case, fd_count receives a number greater than or equal to the number of descriptors. it's giving "two-step, but make it efficient" ✨

---

🌈 PROTOCOLS 🌈

this functionality affects all supported protocols. all of them. every single one. we stan an inclusive king 👑

---

🧚 EXAMPLE 🧚

#include <stdlib.h>

int main(void)
{
  CURLMcode mresult;
  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;

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

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

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

    /* allocate storage for our descriptors */
    ufds = malloc(fd_count * sizeof(struct curl_waitfd));

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

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

    /* Do polling on descriptors in ufds */

    free(ufds);
  } while(!mresult);
}

see how it first asks "how many?" with NULL and 0, then allocates, then asks for realsies? that's the whole two-call pattern in action, and it ate 💅

---

🫶 AVAILABILITY 🫶

Added in curl 8.8.0. so if you're on something older... bestie, upgrade 😭

---

⭐ RETURN VALUE ⭐

this function returns a CURLMcode indicating success or error.

CURLM_OK (0) means everything was OK — slay. non-zero means an error occurred. see libcurl-errors(3) for the full tea 🍵

---

👑 SEE ALSO 👑

• curl_multi_fdset(3)
• curl_multi_perform(3)
• curl_multi_poll(3)
• curl_multi_wait(3)

---

okay that's the whole page, bestie — go poll those descriptors responsibly 🌸💜

this has been libcurl, dated 2026-10-12, signing off with main character energy ✨🎀🦋