CURLMOPT_M...ONNECTIONS(3)

💅 CURLMOPT_MAX_TOTAL_CONNECTIONS(3) 💅

ok so real talk, bestie: this is a page from the Library Functions Manual for libcurl, and it's all about the CURLMOPT_MAX_TOTAL_CONNECTIONS option. it's giving "how many connections am i allowed to have open at once, total" energy. let's get into it 🎀

---

✨ NAME ✨

CURLMOPT_MAX_TOTAL_CONNECTIONS — the max number of simultaneously open connections, periodt 🫶

---

🌸 SYNOPSIS 🌸

#include <curl/curl.h>

CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_TOTAL_CONNECTIONS,
                            long amount);

---

🦋 DESCRIPTION 🦋

okay so you pass a long for the amount. that number becomes the maximum number of simultaneously open connections in total using this multi handle. literally the cap. the ceiling. the vibe check on your connection count 💀

for each new session, libcurl might open a new connection — but only up to the limit you set with CURLMOPT_MAX_TOTAL_CONNECTIONS(3). and if CURLMOPT_PIPELINING(3) is enabled, libcurl can try multiplexing if the host is capable of it. slay, efficiency 💅

when more transfers get added to the multi handle than what can actually be performed because of the set limit, they get queued up waiting for their chance. it's giving backstage at a concert, no cap 😭

⚠️ warning bestie, this part matters: while a transfer is queued up internally waiting for a connection, the CURLOPT_TIMEOUT_MS(3) timeout is counted inclusive of the waiting time. meaning if you set a too narrow timeout, the transfer might never even start before it times out. like it never even got its main character moment. and the CURLOPT_CONNECTTIMEOUT_MS(3) time is also similarly still treated as a per-connect timeout and might expire even before making a new connection is permitted 🔥

changing this value while there are transfers in progress is possible — that's lowkey iconic of it. the new value is then used the next time checks are performed. and lowering the value does not close down any active transfers, it simply does not allow new ones to get made. no ghosting the existing connections, just no new ones invited 🙈

---

⭐ DEFAULT ⭐

0, which means there is no limit. it's then simply controlled by the number of easy handles added concurrently and how much multiplexing is being done. free spirit mode 🌈

---

💜 PROTOCOLS 💜

this functionality affects all supported protocols. every single one. equal opportunity 🫶

---

🍓 EXAMPLE 🍓

int main(void)
{
  CURLM *m = curl_multi_init();
  /* never do more than 15 connections */
  curl_multi_setopt(m, CURLMOPT_MAX_TOTAL_CONNECTIONS, 15L);
}

see how the comment says /* never do more than 15 connections */? that's the whole point. fifteen. not sixteen. fifteen. and it's 15L because it's a long, don't forget the L bestie 🙈

---

🧚 AVAILABILITY 🧚

added in curl 7.30.0. vintage but still relevant ✨

---

🔥 RETURN VALUE 🔥

curl_multi_setopt(3) returns a CURLMcode indicating success or error.

CURLM_OK (0) means everything was OK, non-zero means an error occurred — see libcurl-errors(3) for the whole lineup 💀

---

🌈 SEE ALSO 🌈

• CURLMOPT_MAXCONNECTS(3)
• CURLMOPT_MAX_HOST_CONNECTIONS(3)

---

ok that's the whole page, go forth and cap your connections responsibly 💖 this was libcurl, dated 2026-10-12, and that's the tea bestie 🎀✨