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