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
16Added-in: 7.1
17---
18
19# NAME
20
21CURLOPT_POSTFIELDS - data to POST to server
22
23# SYNOPSIS
24
25~~~c
26#include <curl/curl.h>
27
28CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDS, char *postdata);
29~~~
30
31# DESCRIPTION
32
33Pass a char pointer as parameter, pointing to the data buffer to use in an
34HTTP POST operation or an MQTT subscribe. The data must be formatted and
35encoded the way you want the server to receive it. libcurl does not convert or
36encode it in any way. For example, a web server may assume that this data is
37URL encoded.
38
39The data pointed to is NOT copied by the library: as a consequence, it must be
40preserved by the calling application until the associated transfer finishes.
41This behavior can be changed (so libcurl does copy the data) by instead using
42the CURLOPT_COPYPOSTFIELDS(3) option.
43
44This POST is a normal **application/x-www-form-urlencoded** kind (and libcurl
45sets that Content-Type by default when this option is used), which is commonly
46used by HTML forms. Change Content-Type with CURLOPT_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, which
61then is strictly required if you want to send off null bytes included in the
62data.
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
72Using this option multiple times makes the last set pointer override the
73previous ones. Set it to NULL to disable its use again.
74
75# DEFAULT
76
77NULL
78
79# %PROTOCOLS%
80
81# EXAMPLE
82
83~~~c
84/* send an application/x-www-form-urlencoded POST */
85int main(void)
86{
87  CURL *curl = curl_easy_init();
88  if(curl) {
89    const char *data = "data to send";
90
91    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
92
93    /* size of the POST data if strlen() is not good enough */
94    curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L);
95
96    /* pass in a pointer to the data - libcurl does not copy */
97    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
98
99    curl_easy_perform(curl);
100  }
101
102  /* send an application/json POST */
103  curl = curl_easy_init();
104  if(curl) {
105    const char *json = "{\"name\": \"daniel\"}";
106    struct curl_slist *slist1 = NULL;
107    slist1 = curl_slist_append(slist1, "Content-Type: application/json");
108    slist1 = curl_slist_append(slist1, "Accept: application/json");
109
110    /* set custom headers */
111    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, slist1);
112
113    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
114
115    /* pass in a pointer to the data - libcurl does not copy */
116    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json);
117
118    curl_easy_perform(curl);
119  }
120}
121~~~
122
123# %AVAILABILITY%
124
125# RETURN VALUE
126
127Returns CURLE_OK
128