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