1curl_formadd(3) libcurl Manual curl_formadd(3)
2
6 curl_formadd - add a section to a multipart/formdata HTTP POST
7
9 #include <curl/curl.h>
10 CURLFORMcode curl_formadd(struct curl_httppost **firstitem,
12 struct curl_httppost **lastitem, ...);
13
15 This function is deprecated. Do not use. See curl_mime_init(3) instead.
16 curl_formadd() is used to append sections when building a multi‐
18 part/formdata HTTP POST (sometimes referred to as RFC2388-style posts).
19 Append one section at a time until you have added all the sections you
20 want included and then you pass the firstitem pointer as parameter to
21 CURLOPT_HTTPPOST(3). lastitem is set after each curl_formadd(3) call
22 and on repeated invokes it should be left as set to allow repeated in‐
23 vokes to find the end of the list faster.
24 After the lastitem pointer follow the real arguments.
26 The pointers firstitem and lastitem should both be pointing to NULL in
28 the first call to this function. All list-data will be allocated by the
29 function itself. You must call curl_formfree(3) on the firstitem after
30 the form post has been done to free the resources.
31 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue"
33 header. You can disable this header with CURLOPT_HTTPHEADER(3) as
34 usual.
35 First, there are some basics you need to understand about multi‐
37 part/formdata posts. Each part consists of at least a NAME and a CON‐
38 TENTS part. If the part is made for file upload, there are also a
39 stored CONTENT-TYPE and a FILENAME. Below, we will discuss what op‐
40 tions you use to set these properties in the parts you want to add to
41 your post.
42 The options listed first are for making normal parts. The options from
44 CURLFORM_FILE through CURLFORM_BUFFERLENGTH are for file upload parts.
45
47 CURLFORM_COPYNAME
48 followed by a string which provides the name of this part.
49 libcurl copies the string so your application does not need to
50 keep it around after this function call. If the name is not NUL-
51 terminated, you must set its length with CURLFORM_NAMELENGTH.
52 The name is not allowed to contain zero-valued bytes. The copied
53 data will be freed by curl_formfree(3).
54 CURLFORM_PTRNAME
56 followed by a string which provides the name of this part.
57 libcurl will use the pointer and refer to the data in your ap‐
58 plication, so you must make sure it remains until curl no longer
59 needs it. If the name is not NUL-terminated, you must set its
60 length with CURLFORM_NAMELENGTH. The name is not allowed to
61 contain zero-valued bytes.
62 CURLFORM_COPYCONTENTS
64 followed by a pointer to the contents of this part, the actual
65 data to send away. libcurl copies the provided data, so your ap‐
66 plication does not need to keep it around after this function
67 call. If the data is not null terminated, or if you would like
68 it to contain zero bytes, you must set the length of the name
69 with CURLFORM_CONTENTSLENGTH. The copied data will be freed by
70 curl_formfree(3).
71 CURLFORM_PTRCONTENTS
73 followed by a pointer to the contents of this part, the actual
74 data to send away. libcurl will use the pointer and refer to the
75 data in your application, so you must make sure it remains until
76 curl no longer needs it. If the data is not NUL-terminated, or
77 if you would like it to contain zero bytes, you must set its
78 length with CURLFORM_CONTENTSLENGTH.
79 CURLFORM_CONTENTLEN
81 followed by a curl_off_t value giving the length of the con‐
82 tents. Note that for CURLFORM_STREAM contents, this option is
83 mandatory.
84 If you pass a 0 (zero) for this option, libcurl will instead do
86 a strlen() on the contents to figure out the size. If you really
87 want to send a zero byte content then you must make sure
88 strlen() on the data pointer returns zero.
89 (Option added in 7.46.0)
91 CURLFORM_CONTENTSLENGTH
93 (This option is deprecated. Use CURLFORM_CONTENTLEN instead!)
94 followed by a long giving the length of the contents. Note that
96 for CURLFORM_STREAM contents, this option is mandatory.
97 If you pass a 0 (zero) for this option, libcurl will instead do
99 a strlen() on the contents to figure out the size. If you really
100 want to send a zero byte content then you must make sure
101 strlen() on the data pointer returns zero.
102 CURLFORM_FILECONTENT
104 followed by a filename, causes that file to be read and its con‐
105 tents used as data in this part. This part does not automati‐
106 cally become a file upload part simply because its data was read
107 from a file.
108 The specified file needs to kept around until the associated
110 transfer is done.
111 CURLFORM_FILE
113 followed by a filename, makes this part a file upload part. It
114 sets the filename field to the basename of the provided file‐
115 name, it reads the contents of the file and passes them as data
116 and sets the content-type if the given file match one of the in‐
117 ternally known file extensions. For CURLFORM_FILE the user may
118 send one or more files in one part by providing multiple CURL‐
119 FORM_FILE arguments each followed by the filename (and each
120 CURLFORM_FILE is allowed to have a CURLFORM_CONTENTTYPE).
121 The given upload file has to exist in its full in the file sys‐
123 tem already when the upload starts, as libcurl needs to read the
124 correct file size beforehand.
125 The specified file needs to kept around until the associated
127 transfer is done.
128 CURLFORM_CONTENTTYPE
130 is used in combination with CURLFORM_FILE. Followed by a pointer
131 to a string which provides the content-type for this part, pos‐
132 sibly instead of an internally chosen one.
133 CURLFORM_FILENAME
135 is used in combination with CURLFORM_FILE. Followed by a pointer
136 to a string, it tells libcurl to use the given string as the
137 filename in the file upload part instead of the actual file
138 name.
139 CURLFORM_BUFFER
141 is used for custom file upload parts without use of CURL‐
142 FORM_FILE. It tells libcurl that the file contents are already
143 present in a buffer. The parameter is a string which provides
144 the filename field in the content header.
145 CURLFORM_BUFFERPTR
147 is used in combination with CURLFORM_BUFFER. The parameter is a
148 pointer to the buffer to be uploaded. This buffer must not be
149 freed until after curl_easy_cleanup(3) is called. You must also
150 use CURLFORM_BUFFERLENGTH to set the number of bytes in the buf‐
151 fer.
152 CURLFORM_BUFFERLENGTH
154 is used in combination with CURLFORM_BUFFER. The parameter is a
155 long which gives the length of the buffer.
156 CURLFORM_STREAM
158 Tells libcurl to use the CURLOPT_READFUNCTION(3) callback to get
159 data. The parameter you pass to CURLFORM_STREAM is the pointer
160 passed on to the read callback's fourth argument. If you want
161 the part to look like a file upload one, set the CURLFORM_FILE‐
162 NAME parameter as well. Note that when using CURLFORM_STREAM,
163 CURLFORM_CONTENTSLENGTH must also be set with the total expected
164 length of the part unless the formpost is sent chunked encoded.
165 (Option added in libcurl 7.18.2)
166 CURLFORM_ARRAY
168 Another possibility to send options to curl_formadd() is the
169 CURLFORM_ARRAY option, that passes a struct curl_forms array
170 pointer as its value. Each curl_forms structure element has a
171 CURLformoption and a char pointer. The final element in the ar‐
172 ray must be a CURLFORM_END. All available options can be used in
173 an array, except the CURLFORM_ARRAY option itself. The last ar‐
174 gument in such an array must always be CURLFORM_END.
175 CURLFORM_CONTENTHEADER
177 specifies extra headers for the form POST section. This takes a
178 curl_slist prepared in the usual way using curl_slist_append and
179 appends the list of headers to those libcurl automatically gen‐
180 erates. The list must exist while the POST occurs, if you free
181 it before the post completes you may experience problems.
182 When you have passed the HttpPost pointer to curl_easy_setopt(3)
184 (using the CURLOPT_HTTPPOST(3) option), you must not free the
185 list until after you have called curl_easy_cleanup(3) for the
186 curl handle.
187 See example below.
189
191 struct curl_httppost* post = NULL;
192 struct curl_httppost* last = NULL;
193 char namebuffer[] = "name buffer";
194 long namelength = strlen(namebuffer);
195 char buffer[] = "test buffer";
196 char htmlbuffer[] = "<HTML>test buffer</HTML>";
197 long htmlbufferlength = strlen(htmlbuffer);
198 struct curl_forms forms[3];
199 char file1[] = "my-face.jpg";
200 char file2[] = "your-face.jpg";
201 /* add null character into htmlbuffer, to demonstrate that
202 transfers of buffers containing null characters actually work
203 */
204 htmlbuffer[8] = '\0';
205 /* Add simple name/content section */
207 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
208 CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
209 /* Add simple name/content/contenttype section */
211 curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
212 CURLFORM_COPYCONTENTS, "<HTML></HTML>",
213 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
214 /* Add name/ptrcontent section */
216 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
217 CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
218 /* Add ptrname/ptrcontent section */
220 curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
221 CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
222 namelength, CURLFORM_END);
223 /* Add name/ptrcontent/contenttype section */
225 curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
226 CURLFORM_PTRCONTENTS, htmlbuffer,
227 CURLFORM_CONTENTSLENGTH, htmlbufferlength,
228 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
229 /* Add simple file section */
231 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
232 CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
233 /* Add file/contenttype section */
235 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
236 CURLFORM_FILE, "my-face.jpg",
237 CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
238 /* Add two file section */
240 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
241 CURLFORM_FILE, "my-face.jpg",
242 CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
243 /* Add two file section using CURLFORM_ARRAY */
245 forms[0].option = CURLFORM_FILE;
246 forms[0].value = file1;
247 forms[1].option = CURLFORM_FILE;
248 forms[1].value = file2;
249 forms[2].option = CURLFORM_END;
250 /* Add a buffer to upload */
252 curl_formadd(&post, &last,
253 CURLFORM_COPYNAME, "name",
254 CURLFORM_BUFFER, "data",
255 CURLFORM_BUFFERPTR, record,
256 CURLFORM_BUFFERLENGTH, record_length,
257 CURLFORM_END);
258 /* no option needed for the end marker */
260 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
261 CURLFORM_ARRAY, forms, CURLFORM_END);
262 /* Add the content of a file as a normal post text value */
263 curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
264 CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
265 /* Set the form info */
266 curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
267
269 Deprecated in 7.56.0. Before this release, field names were allowed to
270 contain zero-valued bytes. The pseudo-filename "-" to read stdin is
271 discouraged although still supported, but data is not read before being
272 actually sent: the effective data size can then not be automatically
273 determined, resulting in a chunked encoding transfer. Backslashes and
274 double quotes in field and file names are now escaped before transmis‐
275 sion.
276
278 0 means everything was ok, non-zero means an error occurred correspond‐
279 ing to a CURL_FORMADD_* constant defined in <curl/curl.h>
280
282 curl_easy_setopt(3), curl_formfree(3), curl_mime_init(3)
283libcurl 7.82.0 November 26, 2021 curl_formadd(3)