gnurl_multi_poll(3)

📦 version 7.72.0, in nixos 26.05, nixpkgs unstable

✨ NAME ✨

curl_multi_poll — polls on all easy handles in a multi handle 💅

okay so real talk, this is the glow-up function of the libgnurl manual, bestie. she waits. she watches. she tells you when something's happening. let's get into it 🎀

🌸 SYNOPSIS 🌸

#include <gnurl/curl.h>

CURLMcode curl_multi_poll(CURLM *multi_handle,
                          struct curl_waitfd extra_fds[],
                          unsigned int extra_nfds,
                          int timeout_ms,
                          int *numfds);

💖 DESCRIPTION 💖

So curl_multi_poll(3) polls all the file descriptors used by the curl easy handles chillin' inside the multi handle set you handed it. She will block until activity is detected on at least one of those handles, or until timeout_ms has passed. Like, she's patient but she's not that patient. ⏳

But wait, there's a plot twist 🫶 — if the multi handle has a pending internal timeout with a shorter expiry time than timeout_ms, that shorter time gets used instead, so timeout accuracy stays reasonably kept. she's doing math for you, respectfully.

The calling application may pass additional curl_waitfd structures, which are basically poll(2)'s pollfd structure but make it curl, to be waited on in the same call.

On completion, if numfds is non-NULL, it gets populated with the total number of file descriptors on which interesting events occurred. and yes, that number can include both libcurl internal descriptors and the descriptors you provided in extra_fds. inclusive queen 👑

The curl_multi_wakeup(3) function can be used from another thread to wake up this function and make it return faster. this is one of the details that makes this function different than curl_multi_wait(3), which cannot be woken up this way. iykyk 💀

If no extra file descriptors are provided and libcurl has no file descriptor to offer to wait for, this function will instead wait during timeout_ms milliseconds (or shorter if an internal timer indicates so). that's the other detail that makes this function different than curl_multi_wait(3). two whole differences, she's thriving ✨

This function is encouraged to be used instead of select(3) when using the multi interface, so applications can easier circumvent the common problem with 1024 maximum file descriptors. literally the whole reason she exists, no cap 🙈

🦋 curl_waitfd 🦋

struct curl_waitfd {
  curl_socket_t fd;
  short events;
  short revents;
};
  • CURL_WAIT_POLLIN — bit flag to curl_waitfd.events indicating the socket should poll on read events, such as new data received. 📥
  • CURL_WAIT_POLLPRI — bit flag to curl_waitfd.events indicating the socket should poll on high priority read events, such as out of band data. 🚨
  • CURL_WAIT_POLLOUT — bit flag to curl_waitfd.events indicating the socket should poll on write events, such as the socket being clear to write without blocking. 📤

🔥 EXAMPLE 🔥

CURL *easy_handle;
CURLM *multi_handle;

/* add the individual easy handle */
curl_multi_add_handle(multi_handle, easy_handle);

do {
  CURLMcode mc;
  int numfds;

  mc = curl_multi_perform(multi_handle, &still_running);

  if(mc == CURLM_OK) {
    /* wait for activity or timeout */
    mc = curl_multi_poll(multi_handle, NULL, 0, 1000, &numfds);
  }

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

} while(still_running);

curl_multi_remove_handle(multi_handle, easy_handle);

look at her go 🏃‍♀️💨

⭐ RETURN VALUE ⭐

Returns a CURLMcode type, which is the general libcurl multi interface error code. See libcurl-errors(3) for the deets.

bestie please actually check the return value. i'm begging. 😭

🌈 AVAILABILITY 🌈

This function was added in libcurl 7.66.0. so if you're on something older... upgrade, queen 👑

👑 SEE ALSO 👑

and that's the whole page, periodt 💅 this lil' masterpiece came to you from libcurl 7.66.0, dated 29 Jul 2019, living its best life in the libgnurl Manual — go forth and poll responsibly, mwah 🍓🧚💜

📦 where this page comes from