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