curl_easy_setopt(3)

📦
version 8.18.0 · 26 versions
, in fedora 44

💅 NAME 💅

okay so bestie, welcome to curl_easy_setopt(3) from the Library Functions Manual — the iconic function for setting options for a curl easy handle. 💖

🦋 SYNOPSIS 🦋

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);

🌸 DESCRIPTION 🌸

curl_easy_setopt(3) is literally how you tell libcurl how to behave. ✨ By setting the appropriate options, the application can change libcurl's behavior. All options are set with an option followed by a parameter. That parameter can be a long, a function pointer, an object pointer or a curl_off_t, depending on what the specific option expects.

⚠️ bestie, read this manual carefully — bad input values may cause libcurl to behave badly. 😭

You can only set one option in each function call. A typical application uses many curl_easy_setopt(3) calls in the setup phase.

The handle argument is the return code from a curl_easy_init(3) or curl_easy_duphandle(3) call.

Options set with this function call are sticky. They remain set for all forthcoming transfers performed using this handle. The options are not in any way reset between transfers, so if you want subsequent transfers with different options, you must change them between the transfers. You can optionally reset all options back to internal default with curl_easy_reset(3).

The order in which the options are set does not matter. periodt. 🌈

🎀 STRINGS 🎀

Strings passed to libcurl as 'char *' arguments are copied by the library; the string storage associated to the pointer argument may be discarded or reused after curl_easy_setopt(3) returns. The only exception to this rule is really CURLOPT_POSTFIELDS(3), but the alternative that copies the string CURLOPT_COPYPOSTFIELDS(3) has some usage characteristics you need to read up on. 👀

This function does not accept input strings longer than CURL_MAX_INPUT_LENGTH (8 MB).

libcurl does little to no verification of the contents of provided strings. Passing in "creative octets" like newlines where they are not expected might trigger unexpected results. 💀

Before version 7.17.0, strings were not copied. Instead the user was forced keep them available until libcurl no longer needed them.

✨ OPTIONS ✨

okay continuing the list, bestie — we're in the H's now and it keeps going forever, but that's literally the point 💖

and like… we're not even done yet, there's more list coming, don't go anywhere 🫶✨

🌈 PROTOCOLS 🌈

Okay so this functionality? It affects all supported protocols. Every single one. No gatekeeping. 💅

💻 EXAMPLE 💻

Like, here's the tiniest possible main character program ever:

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

🕰️ AVAILABILITY 🕰️

Added in curl 7.1 — like, ancient. A true elder. Respect her. 🧚

🚦 RETURN VALUE 🚦

This function hands you back a CURLcode that tells you whether it ate or flopped. 🍓

CURLE_OK (0) means everything was literally fine. Anything non-zero means an error happened — check libcurl-errors(3) for the full tea. And ngl, if you set CURLOPT_ERRORBUFFER(3) with curl_easy_setopt(3), there can be an error message chilling in that error buffer when a non-zero comes back. Bestie, that buffer is your friend. 😭

Strings you pass to libcurl must be shorter than 8000000 bytes, otherwise curl_easy_setopt(3) returns CURLE_BAD_FUNCTION_ARGUMENT (added in 7.65.0). No cap, it will not just vibe through that.

CURLE_BAD_FUNCTION_ARGUMENT also shows up when the argument to an option is invalid — like, say, out of range. Invalid looks bad on you, so don't do it. 💀

And if you try to set an option that libcurl straight up does not know about — maybe the library is too old to support it, or maybe the option got removed in a recent version — this function returns CURLE_UNKNOWN_OPTION. If support for the option was disabled at compile-time, you get CURLE_NOT_BUILT_IN instead. Two different moods, two different codes. 🙈

🫶 SEE ALSO 🫶

✨ And that's the whole page, bestie! This one came from the libcurl source, version date 2026-10-12, and it's the manual page for curl_easy_setopt(3). Go forth and set some options. Mwah. 💜🎀💅
📦 where this page comes from