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, struct
12 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've 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
23 invokes 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'll discuss what options
40 you use to set these properties in the parts you want to add to your
41 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 doesn't need to
50 keep it around after this function call. If the name isn't 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
58 application, so you must make sure it remains until curl no
59 longer needs it. If the name isn't NUL-terminated, you must set
60 its 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
66 application doesn't need to keep it around after this function
67 call. If the data isn't null terminated, or if you'd like it to
68 contain zero bytes, you must set the length of the name with
69 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 isn't NUL-terminated, or
77 if you'd like it to contain zero bytes, you must set its length
78 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
117 internally known file extensions. For CURLFORM_FILE the user
118 may send one or more files in one part by providing multiple
119 CURLFORM_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
172 array must be a CURLFORM_END. All available options can be used
173 in an array, except the CURLFORM_ARRAY option itself! The last
174 argument 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've 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've called curl_easy_cleanup(3) for the curl
186 handle.
187 See example below.
189
191 Deprecated in 7.56.0. Before this release, field names were allowed to
192 contain zero-valued bytes. The pseudo-filename "-" to read stdin is
193 discouraged although still supported, but data is not read before being
194 actually sent: the effective data size can then not be automatically
195 determined, resulting in a chunked encoding transfer. Backslashes and
196 double quotes in field and file names are now escaped before transmis‐
197 sion.
198
200 0 means everything was ok, non-zero means an error occurred correspond‐
201 ing to a CURL_FORMADD_* constant defined in <curl/curl.h>
202
204 struct curl_httppost* post = NULL;
205 struct curl_httppost* last = NULL;
206 char namebuffer[] = "name buffer";
207 long namelength = strlen(namebuffer);
208 char buffer[] = "test buffer";
209 char htmlbuffer[] = "<HTML>test buffer</HTML>";
210 long htmlbufferlength = strlen(htmlbuffer);
211 struct curl_forms forms[3];
212 char file1[] = "my-face.jpg";
213 char file2[] = "your-face.jpg";
214 /* add null character into htmlbuffer, to demonstrate that
215 transfers of buffers containing null characters actually work
216 */
217 htmlbuffer[8] = '\0';
218 /* Add simple name/content section */
220 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
221 CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
222 /* Add simple name/content/contenttype section */
224 curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
225 CURLFORM_COPYCONTENTS, "<HTML></HTML>",
226 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
227 /* Add name/ptrcontent section */
229 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
230 CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
231 /* Add ptrname/ptrcontent section */
233 curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
234 CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
235 namelength, CURLFORM_END);
236 /* Add name/ptrcontent/contenttype section */
238 curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
239 CURLFORM_PTRCONTENTS, htmlbuffer,
240 CURLFORM_CONTENTSLENGTH, htmlbufferlength,
241 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
242 /* Add simple file section */
244 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
245 CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
246 /* Add file/contenttype section */
248 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
249 CURLFORM_FILE, "my-face.jpg",
250 CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
251 /* Add two file section */
253 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
254 CURLFORM_FILE, "my-face.jpg",
255 CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
256 /* Add two file section using CURLFORM_ARRAY */
258 forms[0].option = CURLFORM_FILE;
259 forms[0].value = file1;
260 forms[1].option = CURLFORM_FILE;
261 forms[1].value = file2;
262 forms[2].option = CURLFORM_END;
263 /* Add a buffer to upload */
265 curl_formadd(&post, &last,
266 CURLFORM_COPYNAME, "name",
267 CURLFORM_BUFFER, "data",
268 CURLFORM_BUFFERPTR, record,
269 CURLFORM_BUFFERLENGTH, record_length,
270 CURLFORM_END);
271 /* no option needed for the end marker */
273 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
274 CURLFORM_ARRAY, forms, CURLFORM_END);
275 /* Add the content of a file as a normal post text value */
276 curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
277 CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
278 /* Set the form info */
279 curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
280
283 curl_easy_setopt(3), curl_formfree(3), curl_mime_init(3)
284libcurl 7.71.1 March 23, 2020 curl_formadd(3)