1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_POST
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_HTTPPOST (3)
9  - CURLOPT_POSTFIELDS (3)
10  - CURLOPT_PUT (3)
11---
12
13# NAME
14
15CURLOPT_POST - make an HTTP POST
16
17# SYNOPSIS
18
19~~~c
20#include <curl/curl.h>
21
22CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POST, long post);
23~~~
24
25# DESCRIPTION
26
27A parameter set to 1 tells libcurl to do a regular HTTP post. This also makes
28libcurl use a "Content-Type: application/x-www-form-urlencoded" header. This
29is the most commonly used POST method.
30
31Use one of CURLOPT_POSTFIELDS(3) or CURLOPT_COPYPOSTFIELDS(3)
32options to specify what data to post and CURLOPT_POSTFIELDSIZE(3) or
33CURLOPT_POSTFIELDSIZE_LARGE(3) to set the data size.
34
35Optionally, you can provide data to POST using the
36CURLOPT_READFUNCTION(3) and CURLOPT_READDATA(3) options but then
37you must make sure to not set CURLOPT_POSTFIELDS(3) to anything but
38NULL. When providing data with a callback, you must transmit it using chunked
39transfer-encoding or you must set the size of the data with the
40CURLOPT_POSTFIELDSIZE(3) or CURLOPT_POSTFIELDSIZE_LARGE(3)
41options. To enable chunked encoding, you simply pass in the appropriate
42Transfer-Encoding header, see the post-callback.c example.
43
44You can override the default POST Content-Type: header by setting your own
45with CURLOPT_HTTPHEADER(3).
46
47Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
48You can disable this header with CURLOPT_HTTPHEADER(3) as usual.
49
50If you use POST to an HTTP 1.1 server, you can send data without knowing the
51size before starting the POST if you use chunked encoding. You enable this by
52adding a header like "Transfer-Encoding: chunked" with
53CURLOPT_HTTPHEADER(3). With HTTP 1.0 or without chunked transfer, you
54must specify the size in the request. (Since 7.66.0, libcurl automatically
55uses chunked encoding for POSTs if the size is unknown.)
56
57When setting CURLOPT_POST(3) to 1, libcurl automatically sets
58CURLOPT_NOBODY(3) and CURLOPT_HTTPGET(3) to 0.
59
60If you issue a POST request and then want to make a HEAD or GET using the same
61reused handle, you must explicitly set the new request type using
62CURLOPT_NOBODY(3) or CURLOPT_HTTPGET(3) or similar.
63
64When setting CURLOPT_POST(3) to 0, libcurl resets the request type to the
65default to disable the POST. Typically that means gets reset to GET. Instead
66you should set a new request type explicitly as described above.
67
68# DEFAULT
69
700, disabled
71
72# PROTOCOLS
73
74HTTP
75
76# EXAMPLE
77
78~~~c
79int main(void)
80{
81  CURL *curl = curl_easy_init();
82  if(curl) {
83    CURLcode res;
84    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
85    curl_easy_setopt(curl, CURLOPT_POST, 1L);
86
87    /* set up the read callback with CURLOPT_READFUNCTION */
88
89    res = curl_easy_perform(curl);
90
91    curl_easy_cleanup(curl);
92  }
93}
94~~~
95
96# AVAILABILITY
97
98Along with HTTP
99
100# RETURN VALUE
101
102Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
103