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