curl_multi_get_handles(3)

✨ curl_multi_get_handles ✨

okay bestie, this one is from the libcurl manual, page curl_multi_get_handles(3), and it's genuinely one of the cutest little functions once you get what it does 🫶

🌸 NAME 🌸

curl_multi_get_handles — return all added easy handles 💅

🦋 SYNOPSIS 🦋

#include <curl/curl.h>

CURL **curl_multi_get_handles(CURLM *multi_handle);

💖 DESCRIPTION 💖

So basically it returns an array with pointers to all the added easy handles. Slay. The end of the list is marked with a NULL pointer, so you just walk it until you hit that NULL and you're done ✨

And listen — even if you haven't added a single easy handle, it still returns an array, just one that has only a single NULL pointer entry in it. Empty but valid, main character energy 💀

The returned array contains all the handles that are present at the time of the call. The way that timing works: as soon as a handle has been removed from the multi handle, or a handle has been added to it, after the handle array was returned, the two data points are out of sync. So don't be surprised when they disagree 🙈

Also the order of the easy handles within the array is not guaranteed, so please don't index into it and assume anything, bestie 😭

And the important bit: the returned array may not be overwritten, and it must be freed with a call to curl_free(3) after use. Free it. Free ittt 🎀

🌈 PROTOCOLS 🌈

This functionality affects all supported protocols — every single one, no cap 👑

🍓 EXAMPLE 🍓

int main(void)
{
  /* init a multi stack */
  CURLM *multi = curl_multi_init();
  CURL *curl = curl_easy_init();

  if(curl) {
    /* add the transfer */
    curl_multi_add_handle(multi, curl);

    /* extract all added handles */
    CURL **list = curl_multi_get_handles(multi);

    if(list) {
      int i;
      /* remove all added handles */
      for(i = 0; list[i]; i++) {
        curl_multi_remove_handle(multi, list[i]);
      }
      curl_free(list);
    }
  }
}

see how the loop is literally just list[i] until it's falsy? that's the NULL terminator doing its thing, iconic ⭐

🧚 AVAILABILITY 🧚

Added in curl 8.4.0 — so if your curl is older than that, this function simply does not exist for you, sorry babe 💜

🔥 RETURN VALUE 🔥

Returns NULL on failure. Otherwise it returns a pointer to an allocated array 🎀

bestie reminder: that array is allocated, so curl_free(3) it when you're done. Don't leave it hanging 😭

💜 SEE ALSO 💜

• curl_multi_add_handle(3)
• curl_multi_cleanup(3)
• curl_multi_init(3)
• curl_multi_remove_handle(3)

---

and that's the whole page, bestie 🫶 this one's from libcurl, dated 2026-10-12 — go forth and get those handles 💅✨