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, struct
12       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'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 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'll discuss what  options
40       you  use  to  set these properties in the parts you want to add to your
41       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  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
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 isn't 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  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
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 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
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'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
188              See example below.
189

AVAILABILITY

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

RETURN VALUE

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

EXAMPLE

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
219        /* Add simple name/content section */
220        curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
221                     CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
222
223        /* 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
228        /* Add name/ptrcontent section */
229        curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
230                     CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
231
232        /* Add ptrname/ptrcontent section */
233        curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
234                     CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
235                     namelength, CURLFORM_END);
236
237        /* 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
243        /* Add simple file section */
244        curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
245                     CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
246
247        /* 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
252        /* 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
257        /* 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
264        /* 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
272        /* 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
281

SEE ALSO

283       curl_easy_setopt(3), curl_formfree(3), curl_mime_init(3)
284
285
286
287libcurl 7.79.1                 November 04, 2020               curl_formadd(3)
Impressum