CURLOPT_POST(3)

1CURLOPT_POST(3)                     libcurl                    CURLOPT_POST(3)
2
3
4

NAME

6       CURLOPT_POST - make an HTTP POST
7

SYNOPSIS

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

DESCRIPTION

14       A parameter set to 1 tells libcurl to do a regular HTTP post. This will
15       also make the library use a  "Content-Type:  application/x-www-form-ur‐
16       lencoded" header. (This is by far the most commonly used POST method).
17
18       Use  one  of CURLOPT_POSTFIELDS(3) or CURLOPT_COPYPOSTFIELDS(3) options
19       to specify what data  to  post  and  CURLOPT_POSTFIELDSIZE(3)  or  CUR‐
20       LOPT_POSTFIELDSIZE_LARGE(3) to set the data size.
21
22       Optionally,  you  can  provide data to POST using the CURLOPT_READFUNC‐
23       TION(3) and CURLOPT_READDATA(3) options but then you must make sure  to
24       not set CURLOPT_POSTFIELDS(3) to anything but NULL. When providing data
25       with a callback, you must transmit it using  chunked  transfer-encoding
26       or  you must set the size of the data with the CURLOPT_POSTFIELDSIZE(3)
27       or CURLOPT_POSTFIELDSIZE_LARGE(3) options. To enable chunked  encoding,
28       you  simply  pass  in the appropriate Transfer-Encoding header, see the
29       post-callback.c example.
30
31       You can override the default POST Content-Type: header by setting  your
32       own with CURLOPT_HTTPHEADER(3).
33
34       Using  POST  with  HTTP 1.1 implies the use of a "Expect: 100-continue"
35       header.  You can disable  this  header  with  CURLOPT_HTTPHEADER(3)  as
36       usual.
37
38       If  you use POST to an HTTP 1.1 server, you can send data without know‐
39       ing the size before starting the POST if you use chunked encoding.  You
40       enable  this  by adding a header like "Transfer-Encoding: chunked" with
41       CURLOPT_HTTPHEADER(3). With HTTP 1.0 or without chunked  transfer,  you
42       must specify the size in the request. (Since 7.66.0, libcurl will auto‐
43       matically use chunked encoding for POSTs if the size is unknown.)
44
45       When setting CURLOPT_POST(3) to 1, libcurl will automatically set  CUR‐
46       LOPT_NOBODY(3) and CURLOPT_HTTPGET(3) to 0.
47
48       If  you  issue a POST request and then want to make a HEAD or GET using
49       the same re-used handle, you must explicitly set the new  request  type
50       using CURLOPT_NOBODY(3) or CURLOPT_HTTPGET(3) or similar.
51
52       When  setting  CURLOPT_POST(3) to 0, libcurl resets the request type to
53       the default to disable the POST. Typically that would mean  it's  reset
54       to  GET.   Instead  you should set a new request type explicitly as de‐
55       scribed above.
56

DEFAULT

58       0, disabled
59

PROTOCOLS

61       HTTP
62

EXAMPLE

64       CURL *curl = curl_easy_init();
65       if(curl) {
66         curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
67         curl_easy_setopt(curl, CURLOPT_POST, 1L);
68
69         /* set up the read callback with CURLOPT_READFUNCTION */
70
71         ret = curl_easy_perform(curl);
72
73         curl_easy_cleanup(curl);
74       }
75

AVAILABILITY

77       Along with HTTP
78

RETURN VALUE

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