Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

CURLOPT_POST (3)

Name

CURLOPT_POST - make an HTTP POST

Synopsis

#include <curl/curl.h>

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

Description

CURLOPT_POST(3)            curl_easy_setopt options            CURLOPT_POST(3)



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

       Optionally, you can provide data to POST  using  the  CURLOPT_READFUNC-
       TION(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  know-
       ing  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 will auto-
       matically use chunked encoding for POSTs if the size is unknown.)

       When  setting CURLOPT_POST(3) to 1, libcurl will automatically set CUR-
       LOPT_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  re-used handle, you must explicitly set the new request type
       using CURLOPT_NOBODY(3) or 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.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | web/curl         |
       +---------------+------------------+
       |Stability      | Uncommitted      |
       +---------------+------------------+

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



NOTES
       Source code for open source software components in Oracle  Solaris  can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source      was      downloaded       from        https://curl.se/down-
       load/curl-7.83.1.tar.bz2.

       Further information about this software can be found on the open source
       community website at http://curl.haxx.se/.



libcurl 7.83.1                 November 26, 2021               CURLOPT_POST(3)