CURLOPT_MAXLIFETIME_CONN(3)

📦
version 8.18.0 · 23 versions
, in fedora 44

💅 CURLOPT_MAXLIFETIME_CONN(3) 💅

okay so bestie, welcome to the CURLOPT_MAXLIFETIME_CONN(3) page — it lives in the Library Functions Manual and it's literally all about how long a connection is allowed to stick around before it's too old to be reused 👑

✨ NAME ✨

CURLOPT_MAXLIFETIME_CONN — the max lifetime (counted from creation, bestie, from creation) that's allowed for reusing a connection 🎀

🦋 SYNOPSIS 🦋

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXLIFETIME_CONN,
                          long maxlifetime);

💖 DESCRIPTION 💖

So you pass a long as the parameter, and it contains maxlifetime — which is the maximum time in seconds, measured since the connection was created, that you're allowing an existing connection to have in order to even be considered for reuse for this request. no cap, that's the whole vibe 🌸

Here's the lore: libcurl has a connection cache that holds previously used connections. When a new request is about to be done, libcurl goes shopping in that cache and considers any connection that matches for reuse. The CURLOPT_MAXLIFETIME_CONN(3) limit is what stops libcurl from trying connections that are simply too old for reuse. This is genuinely useful for client-side load balancing — iykyk 💅 And if a connection is found in the cache that's older than the maxlifetime you set, then instead of being reused it gets marked for closure. bye bestie 👋

And if you set it to 0, this behavior is disabled entirely: all connections are eligible for reuse. everyone's invited to the party 🎉

🍓 DEFAULT 🍓

24 hours (since 8.17.0). Before that, the default was 0 seconds (i.e., disabled) 🙈

🌈 PROTOCOLS 🌈

This functionality affects all supported protocols ⭐

🧚 EXAMPLE 🧚

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");

    /* only allow each connection to be reused for 30 seconds */
    curl_easy_setopt(curl, CURLOPT_MAXLIFETIME_CONN, 30L);

    curl_easy_perform(curl);
  }
}

🎀 AVAILABILITY 🎀

Added in curl 7.80.0 ✨

💜 RETURN VALUE 💜

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

CURLE_OK (0) means everything was OK 🫶 — and non-zero means an error occurred, so go peek at libcurl-errors(3) 😭

👑 SEE ALSO 👑

okay that's the whole page, you ate that 💅 mwah 💋

— signed with love by libcurl, dated 2026-10-12, and archived forever under CURLOPT_MAXLIFETIME_CONN(3) 🌸🦋💖

📦 where this page comes from