CURLOPT_MAXCONNECTS(3)

💅 CURLOPT_MAXCONNECTS(3) — like, the maximum connection cache size, bestie

okay so this is from the Library Functions Manual, and the whole page is literally about CURLOPT_MAXCONNECTS(3). yes that's the function-slash-option-slash-icon we're stanning today. let's get into it 🎀

---

✨ NAME ✨

CURLOPT_MAXCONNECTS — maximum connection cache size. that's it. that's the tweet. 🦋

---

🌸 SYNOPSIS 🌸

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXCONNECTS, long amount);

so you're passing a long in as amount, and calling it on your handle via curl_easy_setopt. iconic signature, no notes. 🫶

---

💖 DESCRIPTION 💖

okay so you pass a long, and that amount you set is the maximum number of connections that libcurl may keep alive in its connection cache after use. like, after it's done with them, it holds onto them. that's the cache. that's what this caps. 🧚

the default is 5 — and ngl, there is not much point in changing this value unless you are perfectly aware of how this works. like, fr fr, don't just start yanking this number around for the vibe. know what you're doing first. this concerns connections using any of the protocols that support persistent connections.

when it reaches the maximum limit, curl closes the oldest connection present in the cache, so that the number of connections doesn't keep increasing. oldest one gets evicted first. she's done her time. bye bestie 👋

and here's the cautionary part, listen up: if you already have performed transfers with this curl handle, setting a smaller CURLOPT_MAXCONNECTS(3) than before may cause open connections to get closed unnecessarily. so like... don't shrink it mid-relationship, it gets messy. 😭

also important, and this is the plot twist: if you add this easy handle to a multi handle, this setting is not acknowledged. like she does not get the memo. you must instead use curl_multi_setopt(3) and the CURLMOPT_MAXCONNECTS(3) option. periodt.

---

🎀 DEFAULT 🎀

5

five. that's the number. main character number. 💅

---

🌈 PROTOCOLS 🌈

this functionality affects all supported protocols. all of them. every single one. she's versatile like that. ⭐

---

🔥 EXAMPLE 🔥

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
    /* limit the connection cache for this handle to no more than 3 */
    curl_easy_setopt(curl, CURLOPT_MAXCONNECTS, 3L);
    result = curl_easy_perform(curl);
  }
}

look at that comment — /* limit the connection cache for this handle to no more than 3 */ — she said three, max. we respect it. 🙈

---

💜 AVAILABILITY 💜

Added in curl 7.7. vintage. an elder icon. 👑

---

⭐ RETURN VALUE ⭐

curl_easy_setopt(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK. non-zero means an error occurred, and you should go see libcurl-errors(3) for the tea. 🍓

---

🦋 SEE ALSO 🦋

• CURLMOPT_MAXCONNECTS(3)
• CURLMOPT_MAX_HOST_CONNECTIONS(3)
• CURLMOPT_MAX_TOTAL_CONNECTIONS(3)
• CURLOPT_MAXREDIRS(3)

---

ok that's the whole page, go forth and cache responsibly, don't shrink your cache on a live handle, and remember: multi handle = different option entirely. iykyk 💖

libcurl 🌸 2026-10-12 🌸 CURLOPT_MAXCONNECTS(3) — mwah, that's a wrap, love u bestie 🫶✨