---
name: "CURLOPT_POST"
section: "3"
platform: "linux"
package: "curl"
version: "8.23.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/CURLOPT_POST"
---

# CURLOPT\_POST(3)

make an HTTP POST

## NAME

CURLOPT\_POST - make an HTTP POST

## SYNOPSIS

```
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POST, long post);
```

## DESCRIPTION

A parameter set to 1 tells libcurl to do a regular HTTP post. This also makes libcurl use a "Content-Type: application/x-www-form-urlencoded" header. This is the most commonly used POST method.

Use one of *[CURLOPT\_POSTFIELDS(3)](/CURLOPT_POSTFIELDS/3.md)* or *[CURLOPT\_COPYPOSTFIELDS(3)](/CURLOPT_COPYPOSTFIELDS/3.md)* options to specify what data to post and *[CURLOPT\_POSTFIELDSIZE(3)](/CURLOPT_POSTFIELDSIZE/3.md)* or *[CURLOPT\_POSTFIELDSIZE\_LARGE(3)](/CURLOPT_POSTFIELDSIZE_LARGE/3.md)* to set the data size.

Optionally, you can provide data to POST using the *[CURLOPT\_READFUNCTION(3)](/CURLOPT_READFUNCTION/3.md)* and *[CURLOPT\_READDATA(3)](/CURLOPT_READDATA/3.md)* options but then you must make sure to not set *[CURLOPT\_POSTFIELDS(3)](/CURLOPT_POSTFIELDS/3.md)* to anything but NULL. When providing data with a callback, you must transmit it using chunked transfer-encoding or you must set the size of the data with the *[CURLOPT\_POSTFIELDSIZE(3)](/CURLOPT_POSTFIELDSIZE/3.md)* or *[CURLOPT\_POSTFIELDSIZE\_LARGE(3)](/CURLOPT_POSTFIELDSIZE_LARGE/3.md)* options. To enable chunked encoding, pass in the appropriate Transfer-Encoding header, see the post-callback.c example.

You can override the default POST Content-Type: header by setting your own with *[CURLOPT\_HTTPHEADER(3)](/CURLOPT_HTTPHEADER/3.md)*.

Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with *[CURLOPT\_HTTPHEADER(3)](/CURLOPT_HTTPHEADER/3.md)* as usual.

If you use POST to an HTTP 1.1 server, you can send data without knowing the size before starting the POST if you use chunked encoding. You enable this by adding a header like "Transfer-Encoding: chunked" with *[CURLOPT\_HTTPHEADER(3)](/CURLOPT_HTTPHEADER/3.md)*. With HTTP 1.0 or without chunked transfer, you must specify the size in the request. libcurl automatically uses chunked encoding for POSTs if the size is unknown.

When setting *[CURLOPT\_POST(3)](/CURLOPT_POST/3.md)* to 1, libcurl automatically sets *[CURLOPT\_NOBODY(3)](/CURLOPT_NOBODY/3.md)* and *[CURLOPT\_HTTPGET(3)](/CURLOPT_HTTPGET/3.md)* to 0.

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)](/CURLOPT_NOBODY/3.md)* or *[CURLOPT\_HTTPGET(3)](/CURLOPT_HTTPGET/3.md)* or similar.

When setting *[CURLOPT\_POST(3)](/CURLOPT_POST/3.md)* to 0, libcurl resets the request type to the default to disable the POST. Typically that means gets reset to GET. Instead you should set a new request type explicitly as described above.

## DEFAULT

0, disabled

## PROTOCOLS

This functionality affects http only

## 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);
  }
}
```

## AVAILABILITY

Added in curl 7.1

## RETURN VALUE

*[curl\_easy\_setopt(3)](/curl_easy_setopt/3.md)* returns a CURLcode indicating success or error.

CURLE\_OK (0) means everything was OK, non-zero means an error occurred, see *[libcurl-errors(3)](/libcurl-errors/3.md)*.

## SEE ALSO

[**CURLOPT\_HTTPPOST**(3)](/CURLOPT_HTTPPOST/3.md), [**CURLOPT\_POSTFIELDS**(3)](/CURLOPT_POSTFIELDS/3.md), [**CURLOPT\_UPLOAD**(3)](/CURLOPT_UPLOAD/3.md)