1---
2c: Copyright (C) Daniel Stenberg, <daniel.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)
13---
14
15# NAME
16
17CURLOPT_POSTFIELDS - data to POST to server
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDS, char *postdata);
25~~~
26
27# DESCRIPTION
28
29Pass a char pointer as parameter, pointing to the data buffer to use in an
30HTTP POST operation. The data must be formatted and encoded the way you want
31the server to receive it. libcurl does not convert or encode it in any
32way. For example, the web server may assume that this data is URL encoded.
33
34The data pointed to is NOT copied by the library: as a consequence, it must be
35preserved by the calling application until the associated transfer finishes.
36This behavior can be changed (so libcurl does copy the data) by instead using
37the CURLOPT_COPYPOSTFIELDS(3) option.
38
39This POST is a normal **application/x-www-form-urlencoded** kind (and
40libcurl sets that Content-Type by default when this option is used), which is
41commonly used by HTML forms. Change Content-Type with
42CURLOPT_HTTPHEADER(3).
43
44You can use curl_easy_escape(3) to URL encode your data, if
45necessary. It returns a pointer to an encoded string that can be passed as
46*postdata*.
47
48Using CURLOPT_POSTFIELDS(3) implies setting CURLOPT_POST(3) to 1.
49
50If CURLOPT_POSTFIELDS(3) is explicitly set to NULL then libcurl gets the
51POST data from the read callback. If you want to send a zero-byte POST set
52CURLOPT_POSTFIELDS(3) to an empty string, or set CURLOPT_POST(3)
53to 1 and CURLOPT_POSTFIELDSIZE(3) to 0.
54
55libcurl assumes this option points to a null-terminated string unless you also
56set CURLOPT_POSTFIELDSIZE(3) to specify the length of the provided data,
57which then is strictly required if you want to send off null bytes included in
58the data.
59
60Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header,
61and libcurl adds that header automatically if the POST is either known to be
62larger than 1MB or if the expected size is unknown. You can disable this
63header with CURLOPT_HTTPHEADER(3) as usual.
64
65To make **multipart/formdata** posts, check out the
66CURLOPT_MIMEPOST(3) option combined with curl_mime_init(3).
67
68# DEFAULT
69
70NULL
71
72# PROTOCOLS
73
74HTTP
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