CURLOPT_PIPEWAIT(3)

💅 CURLOPT_PIPEWAIT(3) — the libcurl manual, but make it make sense

okay bestie, so this one is a page from the libcurl Library Functions Manual, and it's genuinely one of those options that's like… small but iconic? it's all about ✨patience✨ and not just opening a million connections like a chaotic mess. let's get into it 🫶

---

✨ NAME ✨

CURLOPT_PIPEWAIT — wait for multiplexing. that's it, that's the whole vibe. 🎀

---

🌸 SYNOPSIS 🌸

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PIPEWAIT, long wait);

---

🦋 DESCRIPTION 🦋

okay so the whole thing: you set wait to 1L and you're basically telling libcurl "girl, be patient — wait for a connection to confirm or deny that it can do multiplexing before you keep going." 💅

here's the situation. when libcurl is about to perform a new transfer that allows multiplexing, it checks for existing connections it could use. and if no such connection exists? it immediately continues and creates a fresh new connection to use. like, no hesitation, zero chill, just go. 😭

but when you set this option to 1 — and you've also got CURLMOPT_PIPELINING(3) enabled on the multi handle this transfer is associated with — libcurl instead waits for the connection to reveal whether it's possible to multiplex on before it continues. and that's the slay: it lets libcurl keep the number of connections to a minimum way better when you're using multiplexing protocols. minimal connections, maximum efficiency, main character energy 👑

with this option set, libcurl prefers to wait and reuse an existing connection for multiplexing rather than the opposite — the opposite being "prefer to open a new connection rather than waiting." so it flips that default preference. 🔥

and how long is the waiting time? as long as it takes for the connection to get up and for libcurl to get the necessary response back that informs it about its protocol and support level. so it's not an arbitrary timeout situation, it's just… until the answer arrives. ngl that's kind of fair.

---

🍓 DEFAULT 🍓

0 (off) — so by default it's not doing the patient thing. you have to opt in, bestie.

---

🌈 PROTOCOLS 🌈

this functionality affects http only. that's it. just http. periodt.

---

💖 EXAMPLE 💖

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

    /* now add this easy handle to the multi handle */
  }
}

see that little comment at the end? /* now add this easy handle to the multi handle */ — yeah, that part's on you, the example stops there 🙈

---

⭐ AVAILABILITY ⭐

Added in curl 7.43.0. so it's been around, it's not some brand new experimental thing, we respect the elders 💜

---

🧚 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 — see libcurl-errors(3). easy. go check your return codes, i'm begging you 😭

---

👑 SEE ALSO 👑

• CURLMOPT_MAX_HOST_CONNECTIONS(3)
• CURLMOPT_PIPELINING(3)
• CURLOPT_FORBID_REUSE(3)
• CURLOPT_FRESH_CONNECT(3)

---

and that's the tea ☕ this page came to you from the libcurl source, dated 2026-10-12, and yes it's CURLOPT_PIPEWAIT(3) in case you forgot already 💀 go wait patiently for your multiplexing, bestie, it's giving maturity 🎀✨