curl_easy_upkeep(3)

💖 curl_easy_upkeep(3) 💖

okay so bestie, welcome to the curl_easy_upkeep(3) page — it lives in the Library Functions Manual and it's literally the "keep your connections from ghosting you" function. let's get into it 🫶

---

✨ NAME ✨

curl_easy_upkeep — keep existing connections alive 💅

✨ SYNOPSIS ✨

#include <curl/curl.h>

CURLcode curl_easy_upkeep(CURL *handle);

🌸 DESCRIPTION 🌸

so like, some protocols have these things called "connection upkeep" mechanisms, right? and what they do is send a lil bit of traffic on the connections you already have open, just to keep them alive. why? because it can stop those connections from getting closed by overzealous firewalls, for example 😭 firewalls stay doing the most.

for HTTP/2 there's an upkeep mechanism: when the connection upkeep interval gets exceeded and you call curl_easy_upkeep(3), an HTTP/2 PING frame gets sent on the connection. iconic behavior, no cap 🔥

for MQTT, the upkeep interval defines when to send ping requests so the server doesn't just disconnect you. rude of it, but okay 🎀

the thing is, this function has to be explicitly called for any of that upkeep work to actually happen. it's not doing it behind your back, it's not that kind of function. the connection upkeep interval itself is set with CURLOPT_UPKEEP_INTERVAL_MS(3) ⭐

and here's a fun one: if you call this function on an easy handle that uses a shared connection cache, then upkeep gets performed on the connections in that cache — even if those connections were never used by that easy handle. main character energy honestly. (Added in 8.10.0) 💀

🦋 PROTOCOLS 🦋

this functionality affects all supported protocols — every single one, periodt 👑

🌈 EXAMPLE 🌈

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    /* Make a connection to an HTTP/2 server. */
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");

    /* Set the interval to 30000ms / 30s */
    curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L);

    curl_easy_perform(curl);

    /* Perform more work here. */

    /* While the connection is being held open, curl_easy_upkeep() can be
       called. If curl_easy_upkeep() is called and the time since the last
       upkeep exceeds the interval, then an HTTP/2 PING is sent. */
    curl_easy_upkeep(curl);

    /* Perform more work here. */

    /* always cleanup */
    curl_easy_cleanup(curl);
  }
}

🎀 AVAILABILITY 🎀

added in curl 7.62.0 — so she's been around a minute, iykyk ✨

💜 RETURN VALUE 💜

this function returns a CURLcode that tells you whether it slayed or flopped — success or error, basically.

• CURLE_OK (0) means everything was OK 💖
• non-zero means an error occurred — go see libcurl-errors(3) for the deets

and listen: if CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3), there can be an error message stored in that error buffer when non-zero is returned. so check it, bestie 🫶

💅 SEE ALSO 💅

• CURLOPT_TCP_KEEPALIVE(3)
• CURLOPT_TCP_KEEPIDLE(3)

---

that's the whole page, you ate that 🍓 and just so you know where this masterpiece came from: it's libcurl, dated 2026-10-12, and it's the curl_easy_upkeep(3) page. mwah 💋🧚