curl_multi_setopt(3)

💅 curl_multi_setopt(3) — setting options for a curl multi handle

okay so this is a libcurl manpage, bestie — Library Functions Manual energy, and it's literally all about making your multi handle behave the way you want. sit down, grab a strawberry drink 🍓, we're doing this.

---

✨ NAME ✨

curl_multi_setopt — set options for a curl multi handle. that's it, that's the whole vibe. 🎀

---

🌸 SYNOPSIS 🌸

#include <curl/curl.h>

CURLMcode curl_multi_setopt(CURLM *multi, CURLMoption option, parameter);

like, you pass the multi handle, you pass the option, you pass the parameter. iconic signature, no notes. 💅

---

🦋 DESCRIPTION 🦋

curl_multi_setopt(3) is how you tell a libcurl multi handle how to act. you use the right options and suddenly you're changing libcurl's behavior for that specific multi handle — main character energy for real. ✨

every option gets set with the option followed by its parameter. and the parameter? it's not one thing, bestie, it depends on which option you're using:

• a long
• a function pointer
• an object pointer
• or a curl_off_t

depending on what that specific option expects. so like, read this manual carefully — ngl bad input values may cause libcurl to behave badly, and we do not want that for you. 😭

also important: you can only set one option in each function call. one option per call, periodt. 👑

---

🎀 OPTIONS 🎀

here's the full roster, alphabetical, no skips, no cuts:

• CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE — deprecated 💀 see CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)
• CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE — deprecated 💀 see CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)
• CURLMOPT_MAXCONNECTS — size of connection cache. see CURLMOPT_MAXCONNECTS(3)
• CURLMOPT_MAX_CONCURRENT_STREAMS — max concurrent streams for http2. see CURLMOPT_MAX_CONCURRENT_STREAMS(3)
• CURLMOPT_MAX_HOST_CONNECTIONS — max number of connections to a single host. see CURLMOPT_MAX_HOST_CONNECTIONS(3)
• CURLMOPT_MAX_PIPELINE_LENGTH — deprecated. see CURLMOPT_MAX_PIPELINE_LENGTH(3) 💀
• CURLMOPT_MAX_TOTAL_CONNECTIONS — max simultaneously open connections. see CURLMOPT_MAX_TOTAL_CONNECTIONS(3)
• CURLMOPT_NETWORK_CHANGED — signal that the network has changed. see CURLMOPT_NETWORK_CHANGED(3)
• CURLMOPT_NOTIFYDATA — custom pointer passed to the notify callback. see CURLMOPT_NOTIFYDATA(3)
• CURLMOPT_NOTIFYFUNCTION — callback that receives notifications. see CURLMOPT_NOTIFYFUNCTION(3)
• CURLMOPT_PIPELINING — enable HTTP multiplexing. see CURLMOPT_PIPELINING(3)
• CURLMOPT_PIPELINING_SERVER_BL — deprecated. see CURLMOPT_PIPELINING_SERVER_BL(3) 💀
• CURLMOPT_PIPELINING_SITE_BL — deprecated. see CURLMOPT_PIPELINING_SITE_BL(3) 💀
• CURLMOPT_PUSHDATA — pointer to pass to push callback. see CURLMOPT_PUSHDATA(3)
• CURLMOPT_PUSHFUNCTION — callback that approves or denies server pushes. see CURLMOPT_PUSHFUNCTION(3)
• CURLMOPT_SOCKETDATA — custom pointer passed to the socket callback. see CURLMOPT_SOCKETDATA(3)
• CURLMOPT_SOCKETFUNCTION — callback informed about what to wait for. see CURLMOPT_SOCKETFUNCTION(3)
• CURLMOPT_TIMERDATA — custom pointer to pass to timer callback. see CURLMOPT_TIMERDATA(3)
• CURLMOPT_TIMERFUNCTION — callback to receive timeout values. see CURLMOPT_TIMERFUNCTION(3)

---

🌈 PROTOCOLS 🌈

this functionality affects all supported protocols. all of them. every single one. we love an inclusive queen. 👑

---

💜 EXAMPLE 💜

okay here's a whole little program, and yes we're limiting the simultaneous connections because that's just good manners:

#define MAX_PARALLEL 45

int main(void)
{
  CURLM *multi = curl_multi_init();

  /* Limit the amount of simultaneous connections curl should allow: */
  curl_multi_setopt(multi, CURLMOPT_MAXCONNECTS, (long)MAX_PARALLEL);
}

MAX_PARALLEL is 45, in case you were wondering. it's giving "I set boundaries." 🫶

---

⭐ AVAILABILITY ⭐

added in curl 7.15.4. vintage but still serving. ✨

---

🔥 RETURN VALUE 🔥

this function returns a CURLMcode indicating success or error.

• CURLM_OK (0) — everything was OK, slay 🎉
• non-zero — an error occurred, see libcurl-errors(3)

small but crucial note: it returns a CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl does not know of. so like, vibe check your libcurl version first, bestie. 🙈

---

🧚 SEE ALSO 🧚

curl_multi_cleanup(3), curl_multi_info_read(3), curl_multi_init(3), curl_multi_socket(3)

---

and that's the whole page, no cap. go forth and set exactly one option per call 💖

— with love from the libcurl girlies, dated 2026-10-12 🦋 (yes the source line said libcurl, yes it said 2026-10-12, and yes I remembered it for you 🫶)