CURL_MULTI_REMOVE_HANDLE(3)

💅 curl_multi_remove_handle(3) — Library Functions Manual

okay bestie, so this one is from the libcurl manual, and it's literally the "break up with your easy handle" function 🫶. Let's get into it.

---

✨ NAME ✨

curl_multi_remove_handle — take an easy handle out of a multi session, like removing someone from the group chat 💔

---

🌸 SYNOPSIS 🌸

#include <curl/curl.h>

CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle);

---

🦋 DESCRIPTION 🦋

So what this does: it removes a given easy_handle from the multi_handle. No cap — it means that specific easy handle is now removed from this multi handle's control, like it's been uninvited from the party and the bouncer has your name on the list 🚫.

Once the easy handle has been removed from a multi stack, it is, and I quote, again perfectly legal to invoke curl_easy_perform(3) on this easy handle. so like, it's free again, it's a main character again, it can go do solo stuff ✨

Removing an easy handle while it's being used is also perfectly legal — and it effectively halts the transfer in progress that involves that easy handle. everyone else? untouched. all other easy handles and transfers remain unaffected. we love a clean exit 💅

It's fine to remove a handle at any time during a transfer — the one exception? just not from within any libcurl callback function. so like, not while you're inside a callback, bestie, that's the no-go zone 🙈

oh and heads up: removing an easy handle from the multi handle before the corresponding transfer is complete might cause libcurl to close the connection — that happens if the state of it and the internal protocol handler deem it necessary. Otherwise, libcurl keeps that connection alive in the connection pool associated with the multi handle, just chilling there, ready to get reused for a future transfer using this multi handle. connection pool stays slaying 🔥

---

🌈 PROTOCOLS 🌈

This functionality affects all supported protocols. all of them. every single one 👑

---

⭐ EXAMPLE ⭐

int main(void)
{
  CURLM *multi = curl_multi_init();
  int queued = 0;

  /* when an easy handle has completed, remove it */
  CURLMsg *msg = curl_multi_info_read(multi, &queued);
  if(msg) {
    if(msg->msg == CURLMSG_DONE) {
      /* a transfer ended */
      fprintf(stderr, "Transfer completed\n");
      curl_multi_remove_handle(multi, msg->easy_handle);
    }
  }
}

like, look at her go — finished transfer, handle removed, vibes immaculate 🎀

---

🧚 AVAILABILITY 🧚

Added in curl 7.9.6 — she's been iconic since day one, fr fr.

---

💜 RETURN VALUE 💜

This function returns a CURLMcode indicating success or error.

CURLM_OK (0) means everything was OK 😌 — non-zero means an error occurred, so go check libcurl-errors(3) and figure out what happened 💀

---

🍓 SEE ALSO 🍓

• curl_multi_add_handle(3) — the make-up function, aka the other half of this duo 💖
• curl_multi_cleanup(3) — the actual end of the era
• curl_multi_init(3) — where it all begins ✨

---

that's the whole page, bestie — go forth and remove handles responsibly 🦋

mwah 💋 — libcurl, dated 2026-10-12, page curl_multi_remove_handle(3) — see you in the next manpage, iykyk 🎀