1curl_formadd(3)                 libcurl Manual                 curl_formadd(3)
2
3
4

NAME

6       curl_formadd - add a section to a multipart/formdata HTTP POST
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLFORMcode curl_formadd(struct curl_httppost **firstitem,
12                                 struct curl_httppost **lastitem, ...);
13

DESCRIPTION

15       This function is deprecated. Do not use. See curl_mime_init(3) instead.
16
17       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
25       After the lastitem pointer follow the real arguments.
26
27       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
32       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
36       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
43       The  options listed first are for making normal parts. The options from
44       CURLFORM_FILE through CURLFORM_BUFFERLENGTH are for file upload parts.
45

OPTIONS

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
55       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
63       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
72       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
80       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
85              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
90              (Option added in 7.46.0)
91
92       CURLFORM_CONTENTSLENGTH
93              (This option is deprecated. Use CURLFORM_CONTENTLEN instead!)
94
95              followed by a long giving the length of the contents. Note  that
96              for CURLFORM_STREAM contents, this option is mandatory.
97
98              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
103       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
109              The  specified  file  needs  to kept around until the associated
110              transfer is done.
111
112       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
122              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
126              The  specified  file  needs  to kept around until the associated
127              transfer is done.
128
129       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
134       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
140       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
146       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
153       CURLFORM_BUFFERLENGTH
154              is used in combination with CURLFORM_BUFFER. The parameter is  a
155              long which gives the length of the buffer.
156
157       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
167       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
176       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
183              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
188              See example below.
189

EXAMPLE

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
206        /* Add simple name/content section */
207        curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
208                     CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
209
210        /* 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
215        /* Add name/ptrcontent section */
216        curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
217                     CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
218
219        /* Add ptrname/ptrcontent section */
220        curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
221                     CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
222                     namelength, CURLFORM_END);
223
224        /* 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
230        /* Add simple file section */
231        curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
232                     CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
233
234        /* 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
239        /* 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
244        /* 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
251        /* 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
259        /* 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

AVAILABILITY

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

RETURN VALUE

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

SEE ALSO

282       curl_easy_setopt(3), curl_formfree(3), curl_mime_init(3)
283
284
285
286libcurl 7.85.0                   May 17, 2022                  curl_formadd(3)
Impressum