1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_POSTFIELDS 5Section: 3 6Source: libcurl 7See-also: 8 - CURLOPT_COPYPOSTFIELDS (3) 9 - CURLOPT_MIMEPOST (3) 10 - CURLOPT_POSTFIELDSIZE (3) 11 - CURLOPT_READFUNCTION (3) 12 - CURLOPT_UPLOAD (3) 13Protocol: 14 - HTTP 15 - MQTT 16--- 17 18# NAME 19 20CURLOPT_POSTFIELDS - data to POST to server 21 22# SYNOPSIS 23 24~~~c 25#include <curl/curl.h> 26 27CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDS, char *postdata); 28~~~ 29 30# DESCRIPTION 31 32Pass a char pointer as parameter, pointing to the data buffer to use in an 33HTTP POST operation or an MQTT subscribe. The data must be formatted and 34encoded the way you want the server to receive it. libcurl does not convert or 35encode it in any way. For example, a web server may assume that this data is 36URL encoded. 37 38The data pointed to is NOT copied by the library: as a consequence, it must be 39preserved by the calling application until the associated transfer finishes. 40This behavior can be changed (so libcurl does copy the data) by instead using 41the CURLOPT_COPYPOSTFIELDS(3) option. 42 43This POST is a normal **application/x-www-form-urlencoded** kind (and 44libcurl sets that Content-Type by default when this option is used), which is 45commonly used by HTML forms. Change Content-Type with 46CURLOPT_HTTPHEADER(3). 47 48You can use curl_easy_escape(3) to URL encode your data, if 49necessary. It returns a pointer to an encoded string that can be passed as 50*postdata*. 51 52Using CURLOPT_POSTFIELDS(3) implies setting CURLOPT_POST(3) to 1. 53 54If CURLOPT_POSTFIELDS(3) is explicitly set to NULL then libcurl gets the POST 55data from the read callback. To send a zero-length (empty) POST, set 56CURLOPT_POSTFIELDS(3) to an empty string, or set CURLOPT_POST(3) to 1 and 57CURLOPT_POSTFIELDSIZE(3) to 0. 58 59libcurl assumes this option points to a null-terminated string unless you also 60set CURLOPT_POSTFIELDSIZE(3) to specify the length of the provided data, 61which then is strictly required if you want to send off null bytes included in 62the data. 63 64Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header, 65and libcurl adds that header automatically if the POST is either known to be 66larger than 1MB or if the expected size is unknown. You can disable this 67header with CURLOPT_HTTPHEADER(3) as usual. 68 69To make **multipart/formdata** posts, check out the 70CURLOPT_MIMEPOST(3) option combined with curl_mime_init(3). 71 72# DEFAULT 73 74NULL 75 76# EXAMPLE 77 78~~~c 79/* send an application/x-www-form-urlencoded POST */ 80int main(void) 81{ 82 CURL *curl = curl_easy_init(); 83 if(curl) { 84 const char *data = "data to send"; 85 86 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 87 88 /* size of the POST data if strlen() is not good enough */ 89 curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); 90 91 /* pass in a pointer to the data - libcurl does not copy */ 92 curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); 93 94 curl_easy_perform(curl); 95 } 96 97 /* send an application/json POST */ 98 curl = curl_easy_init(); 99 if(curl) { 100 const char *json = "{\"name\": \"daniel\"}"; 101 struct curl_slist *slist1 = NULL; 102 slist1 = curl_slist_append(slist1, "Content-Type: application/json"); 103 slist1 = curl_slist_append(slist1, "Accept: application/json"); 104 105 /* set custom headers */ 106 curl_easy_setopt(curl, CURLOPT_HTTPHEADER, slist1); 107 108 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 109 110 /* pass in a pointer to the data - libcurl does not copy */ 111 curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json); 112 113 curl_easy_perform(curl); 114 } 115} 116~~~ 117 118# AVAILABILITY 119 120Always 121 122# RETURN VALUE 123 124Returns CURLE_OK 125