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) or CURLOPT_COPYPOSTFIELDS(3) options to specify what data
       to post and CURLOPT_POSTFIELDSIZE(3) or CURLOPT_POSTFIELDSIZE_LARGE(3)  to  set  the  data
       size.

       Optionally,   you   can  provide  data  to  POST  using  the  CURLOPT_READFUNCTION(3)  and
       CURLOPT_READDATA(3) options but then you must make sure to not  set  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
       CURLOPT_POSTFIELDSIZE(3)  or  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
       CURLOPT_HTTPHEADER(3).

       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.

       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). With HTTP 1.0 or without chunked
       transfer, you must specify the size in the request. (Since 7.66.0,  libcurl  automatically
       uses chunked encoding for POSTs if the size is unknown.)

       When  setting  CURLOPT_POST(3)  to  1,  libcurl  automatically  sets CURLOPT_NOBODY(3) and
       CURLOPT_HTTPGET(3) 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)  or
       CURLOPT_HTTPGET(3) or similar.

       When setting CURLOPT_POST(3) 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 res;
           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 */

           res = curl_easy_perform(curl);

           curl_easy_cleanup(curl);
         }
       }

AVAILABILITY

       Added in curl 7.1

RETURN VALUE

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

SEE ALSO

       CURLOPT_HTTPPOST(3), CURLOPT_POSTFIELDS(3), CURLOPT_UPLOAD(3)