CURLOPT_POST(3)            curl_easy_setopt options            CURLOPT_POST(3)

NAME
       CURLOPT_POST - request 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 will
       also make the library use a "Content-Type: application/x-www-form-
       urlencoded" header. (This is by far the most commonly used POST
       method).

       Use one of _POSTFIELDS&section=3">CURLOPT_POSTFIELDS(3) or _COPYPOSTFIELDS&section=3">CURLOPT_COPYPOSTFIELDS(3) options
       to specify what data to post and _POSTFIELDSIZE&section=3">CURLOPT_POSTFIELDSIZE(3) or
       _POSTFIELDSIZE_LARGE&section=3">CURLOPT_POSTFIELDSIZE_LARGE(3) to set the data size.

       Optionally, you can provide data to POST using the
       _READFUNCTION&section=3">CURLOPT_READFUNCTION(3) and _READDATA&section=3">CURLOPT_READDATA(3) options but then you
       must make sure to not set _POSTFIELDS&section=3">CURLOPT_POSTFIELDS(3) 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
       _POSTFIELDSIZE&section=3">CURLOPT_POSTFIELDSIZE(3) or _POSTFIELDSIZE_LARGE&section=3">CURLOPT_POSTFIELDSIZE_LARGE(3) options. To
       enable chunked encoding, you simply 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 _HTTPHEADER&section=3">CURLOPT_HTTPHEADER(3).

       Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue"
       header.  You can disable this header with _HTTPHEADER&section=3">CURLOPT_HTTPHEADER(3) 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 _HTTPHEADER&section=3">CURLOPT_HTTPHEADER(3). With HTTP 1.0 or without chunked transfer,
       you must specify the size in the request. (Since 7.66.0, libcurl will
       automatically use chunked encoding for POSTs if the size is unknown.)

       When setting _POST&section=3">CURLOPT_POST(3) to 1, libcurl will automatically set
       _NOBODY&section=3">CURLOPT_NOBODY(3) and _HTTPGET&section=3">CURLOPT_HTTPGET(3) to 0.

       If you issue a POST request and then want to make a HEAD or GET using
       the same re-used handle, you must explicitly set the new request type
       using _NOBODY&section=3">CURLOPT_NOBODY(3) or _HTTPGET&section=3">CURLOPT_HTTPGET(3) or similar.

DEFAULT
       0, disabled

PROTOCOLS
       HTTP

EXAMPLE
       CURL *curl = curl_easy_init();
       if(curl) {
         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 */

         ret = curl_easy_perform(curl);

         curl_easy_cleanup(curl);
       }

AVAILABILITY
       Along with HTTP

RETURN VALUE
       Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.

SEE ALSO
       CURLOPT_POSTFIELDS(3), CURLOPT_HTTPPOST(3),

libcurl 7.77.0                 November 4, 2020                CURLOPT_POST(3)