CURLOPT_POST(3)

💅 CURLOPT_POST — the "make it a POST" button, bestie

so this page is CURLOPT_POST(3), part of the libcurl manual, and honestly it's one of the most-used little switches in the whole library. let's get into it 🫶

---

✨ NAME ✨

CURLOPT_POST — like, make it an HTTP POST. that's the whole vibe. no cap.

---

🌸 SYNOPSIS 🌸

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POST, long post);

---

🎀 DESCRIPTION 🎀

okay so picture this: you set this parameter to 1 and libcurl is immediately like "say less" and does a regular HTTP post. and not only that — it also gives you a Content-Type: application/x-www-form-urlencoded header for free. this is literally the most commonly used POST method out there. main character energy 💅

now, to actually tell it what to post, you use one of CURLOPT_POSTFIELDS(3) or CURLOPT_COPYPOSTFIELDS(3), and to set the data size you reach for CURLOPT_POSTFIELDSIZE(3) or CURLOPT_POSTFIELDSIZE_LARGE(3). slay.

like, optionally, you can feed it data with the CURLOPT_READFUNCTION(3) and CURLOPT_READDATA(3) options instead — but then you must make sure you don't set CURLOPT_POSTFIELDS(3) to anything but NULL. not optional, bestie, that's a hard requirement. and when you're providing data with a callback, you have to transmit it using chunked transfer-encoding, or you have to set the size of the data with the CURLOPT_POSTFIELDSIZE(3) or CURLOPT_POSTFIELDSIZE_LARGE(3) options. to enable chunked encoding you simply pass in the appropriate Transfer-Encoding header — go look at the post-callback.c example, it's giving tutorial excellence ✨

you can also override that default POST Content-Type: header by setting your own with CURLOPT_HTTPHEADER(3). iconic, you do you.

ngl there's a lil caveat here: using POST with HTTP 1.1 implies the use of a Expect: 100-continue header. you can disable this header with CURLOPT_HTTPHEADER(3) as usual. consider this your heads-up 💀

and here's the tea on sizes — if you use POST to an HTTP 1.1 server, you can send data without knowing the size before starting the POST, as long as you use chunked encoding. you enable it by adding a header like Transfer-Encoding: chunked with CURLOPT_HTTPHEADER(3). with HTTP 1.0, or without chunked transfer, you must specify the size in the request. (and since 7.66.0, libcurl automatically uses chunked encoding for POSTs if the size is unknown — she learned to do it herself, we love growth 🌱)

when you set CURLOPT_POST(3) to 1, libcurl automatically sets CURLOPT_NOBODY(3) and CURLOPT_HTTPGET(3) to 0. automatic. no notes.

now the part people forget 🙈 — if you issue a POST request and then want to make a HEAD or GET using the same reused handle, you must explicitly set the new request type using CURLOPT_NOBODY(3) or CURLOPT_HTTPGET(3) or similar. it will NOT just figure it out for you, bestie.

and when you set CURLOPT_POST(3) to 0, libcurl resets the request type to the default to disable the POST. typically that means it gets reset to GET. but instead of relying on that, you should set a new request type explicitly as described above. much cleaner, much less chaos 🦋

---

⭐ DEFAULT ⭐

0, disabled. she's off until you tell her otherwise 💤

---

🌈 PROTOCOLS 🌈

this functionality affects http only. http girlies only, sorry to the rest of y'all 🎀

---

🔥 EXAMPLE 🔥

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

    /* set up the read callback with CURLOPT_READFUNCTION */

    result = curl_easy_perform(curl);

    curl_easy_cleanup(curl);
  }
}

look at that. clean, simple, ate 💅

---

🦋 AVAILABILITY 🦋

added in curl 7.1 — she's been here since the early days, a true veteran 👑

---

💖 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) for the whole dramatic saga 😭

---

🌸 SEE ALSO 🌸

• CURLOPT_HTTPPOST(3)
• CURLOPT_POSTFIELDS(3)
• CURLOPT_UPLOAD(3)

---

k that's the whole page bestie, go forth and POST responsibly 🫶✨

mwah 💋 — this was the libcurl manual page for CURLOPT_POST, dated 2026-10-12. see you in the next manpage, love u, bye 👋💜