docs/libcurl/curl_formadd.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" **************************************************************************
  22 .TH curl_formadd 3 "October 08, 2017" "libcurl 7.59.0" "libcurl Manual"
  23
  24 .SH NAME
  25 curl_formadd - add a section to a multipart/formdata HTTP POST
  26 .SH SYNOPSIS
  27 .B #include <curl/curl.h>
  28 .sp
  29 .BI "CURLFORMcode curl_formadd(struct curl_httppost ** " firstitem,
  30 .BI "struct curl_httppost ** " lastitem, " ...);"
  31 .ad
  32 .SH DESCRIPTION
  33 This function is deprecated. Do not use! See \fIcurl_mime_init(3)\fP instead!
  34
  35 curl_formadd() is used to append sections when building a multipart/formdata
  36 HTTP POST (sometimes referred to as RFC2388-style posts). Append one section
  37 at a time until you've added all the sections you want included and then you
  38 pass the \fIfirstitem\fP pointer as parameter to \fICURLOPT_HTTPPOST(3)\fP.
  39 \fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated
  40 invokes it should be left as set to allow repeated invokes to find the end of
  41 the list faster.
  42
  43 After the \fIlastitem\fP pointer follow the real arguments.
  44
  45 The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to
  46 NULL in the first call to this function. All list-data will be allocated by
  47 the function itself. You must call \fIcurl_formfree(3)\fP on the
  48 \fIfirstitem\fP after the form post has been done to free the resources.
  49
  50 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
  51 You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
  52
  53 First, there are some basics you need to understand about multipart/formdata
  54 posts. Each part consists of at least a NAME and a CONTENTS part. If the part
  55 is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME.
  56 Below, we'll discuss what options you use to set these properties in the
  57 parts you want to add to your post.
  58
  59 The options listed first are for making normal parts. The options from
  60 \fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload
  61 parts.
  62 .SH OPTIONS
  63 .IP CURLFORM_COPYNAME
  64 followed by a string which provides the \fIname\fP of this part. libcurl
  65 copies the string so your application doesn't need to keep it around after
  66 this function call. If the name isn't NUL-terminated, you must set its length
  67 with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to contain
  68 zero-valued bytes. The copied data will be freed by \fIcurl_formfree(3)\fP.
  69 .IP CURLFORM_PTRNAME
  70 followed by a string which provides the \fIname\fP of this part. libcurl
  71 will use the pointer and refer to the data in your application, so you
  72 must make sure it remains until curl no longer needs it. If the name
  73 isn't NUL-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP.
  74 The \fIname\fP is not allowed to contain zero-valued bytes.
  75 .IP CURLFORM_COPYCONTENTS
  76 followed by a pointer to the contents of this part, the actual data
  77 to send away. libcurl copies the provided data, so your application doesn't
  78 need to keep it around after this function call. If the data isn't null
  79 terminated, or if you'd like it to contain zero bytes, you must
  80 set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied
  81 data will be freed by \fIcurl_formfree(3)\fP.
  82 .IP CURLFORM_PTRCONTENTS
  83 followed by a pointer to the contents of this part, the actual data
  84 to send away. libcurl will use the pointer and refer to the data in your
  85 application, so you must make sure it remains until curl no longer needs it.
  86 If the data isn't NUL-terminated, or if you'd like it to contain zero bytes,
  87 you must set its length  with \fBCURLFORM_CONTENTSLENGTH\fP.
  88 .IP CURLFORM_CONTENTLEN
  89 followed by a curl_off_t value giving the length of the contents. Note that
  90 for \fICURLFORM_STREAM\fP contents, this option is mandatory.
  91
  92 If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
  93 the contents to figure out the size. If you really want to send a zero byte
  94 content then you must make sure strlen() on the data pointer returns zero.
  95
  96 (Option added in 7.46.0)
  97 .IP CURLFORM_CONTENTSLENGTH
  98 (This option is deprecated. Use \fICURLFORM_CONTENTLEN\fP instead!)
  99
 100 followed by a long giving the length of the contents. Note that for
 101 \fICURLFORM_STREAM\fP contents, this option is mandatory.
 102
 103 If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
 104 the contents to figure out the size. If you really want to send a zero byte
 105 content then you must make sure strlen() on the data pointer returns zero.
 106 .IP CURLFORM_FILECONTENT
 107 followed by a filename, causes that file to be read and its contents used
 108 as data in this part. This part does \fInot\fP automatically become a file
 109 upload part simply because its data was read from a file.
 110
 111 The specified file needs to kept around until the associated transfer is done.
 112 .IP CURLFORM_FILE
 113 followed by a filename, makes this part a file upload part. It sets the
 114 \fIfilename\fP field to the basename of the provided filename, it reads the
 115 contents of the file and passes them as data and sets the content-type if the
 116 given file match one of the internally known file extensions.  For
 117 \fBCURLFORM_FILE\fP the user may send one or more files in one part by
 118 providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
 119 (and each \fICURLFORM_FILE\fP is allowed to have a
 120 \fICURLFORM_CONTENTTYPE\fP).
 121
 122 The given upload file has to exist in its full in the file system already when
 123 the upload starts, as libcurl needs to read the correct file size beforehand.
 124
 125 The specified file needs to kept around until the associated transfer is done.
 126 .IP CURLFORM_CONTENTTYPE
 127 is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
 128 string which provides the content-type for this part, possibly instead of an
 129 internally chosen one.
 130 .IP CURLFORM_FILENAME
 131 is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
 132 string, it tells libcurl to use the given string as the \fIfilename\fP in the
 133 file upload part instead of the actual file name.
 134 .IP CURLFORM_BUFFER
 135 is used for custom file upload parts without use of \fICURLFORM_FILE\fP.  It
 136 tells libcurl that the file contents are already present in a buffer.  The
 137 parameter is a string which provides the \fIfilename\fP field in the content
 138 header.
 139 .IP CURLFORM_BUFFERPTR
 140 is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer
 141 to the buffer to be uploaded. This buffer must not be freed until after
 142 \fIcurl_easy_cleanup(3)\fP is called. You must also use
 143 \fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer.
 144 .IP CURLFORM_BUFFERLENGTH
 145 is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a
 146 long which gives the length of the buffer.
 147 .IP CURLFORM_STREAM
 148 Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get
 149 data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on
 150 to the read callback's fourth argument. If you want the part to look like a
 151 file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that
 152 when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be
 153 set with the total expected length of the part unless the formpost is sent
 154 chunked encoded. (Option added in libcurl 7.18.2)
 155 .IP CURLFORM_ARRAY
 156 Another possibility to send options to curl_formadd() is the
 157 \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
 158 its value. Each curl_forms structure element has a CURLformoption and a char
 159 pointer. The final element in the array must be a CURLFORM_END. All available
 160 options can be used in an array, except the CURLFORM_ARRAY option itself!  The
 161 last argument in such an array must always be \fBCURLFORM_END\fP.
 162 .IP CURLFORM_CONTENTHEADER
 163 specifies extra headers for the form POST section.  This takes a curl_slist
 164 prepared in the usual way using \fBcurl_slist_append\fP and appends the list
 165 of headers to those libcurl automatically generates. The list must exist while
 166 the POST occurs, if you free it before the post completes you may experience
 167 problems.
 168
 169 When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
 170 the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after
 171 you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
 172
 173 See example below.
 174 .SH AVAILABILITY
 175 Deprecated in 7.56.0. Before this release, field names were allowed to
 176 contain zero-valued bytes. The pseudo-filename "-" to read stdin is
 177 discouraged although still supported, but data is not read before being
 178 actually sent: the effective data size can then not be automatically
 179 determined, resulting in a chunked encoding transfer.
 180 .SH RETURN VALUE
 181 0 means everything was ok, non-zero means an error occurred corresponding
 182 to a CURL_FORMADD_* constant defined in
 183 .I <curl/curl.h>
 184 .SH EXAMPLE
 185 .nf
 186
 187  struct curl_httppost* post = NULL;
 188  struct curl_httppost* last = NULL;
 189  char namebuffer[] = "name buffer";
 190  long namelength = strlen(namebuffer);
 191  char buffer[] = "test buffer";
 192  char htmlbuffer[] = "<HTML>test buffer</HTML>";
 193  long htmlbufferlength = strlen(htmlbuffer);
 194  struct curl_forms forms[3];
 195  char file1[] = "my-face.jpg";
 196  char file2[] = "your-face.jpg";
 197  /* add null character into htmlbuffer, to demonstrate that
 198     transfers of buffers containing null characters actually work
 199  */
 200  htmlbuffer[8] = '\\0';
 201
 202  /* Add simple name/content section */
 203  curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
 204               CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
 205
 206  /* Add simple name/content/contenttype section */
 207  curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
 208               CURLFORM_COPYCONTENTS, "<HTML></HTML>",
 209               CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
 210
 211  /* Add name/ptrcontent section */
 212  curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
 213               CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
 214
 215  /* Add ptrname/ptrcontent section */
 216  curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
 217               CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
 218               namelength, CURLFORM_END);
 219
 220  /* Add name/ptrcontent/contenttype section */
 221  curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
 222               CURLFORM_PTRCONTENTS, htmlbuffer,
 223               CURLFORM_CONTENTSLENGTH, htmlbufferlength,
 224               CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
 225
 226  /* Add simple file section */
 227  curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
 228               CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
 229
 230  /* Add file/contenttype section */
 231  curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
 232               CURLFORM_FILE, "my-face.jpg",
 233               CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
 234
 235  /* Add two file section */
 236  curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
 237               CURLFORM_FILE, "my-face.jpg",
 238               CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
 239
 240  /* Add two file section using CURLFORM_ARRAY */
 241  forms[0].option = CURLFORM_FILE;
 242  forms[0].value  = file1;
 243  forms[1].option = CURLFORM_FILE;
 244  forms[1].value  = file2;
 245  forms[2].option  = CURLFORM_END;
 246
 247  /* Add a buffer to upload */
 248  curl_formadd(&post, &last,
 249               CURLFORM_COPYNAME, "name",
 250               CURLFORM_BUFFER, "data",
 251               CURLFORM_BUFFERPTR, record,
 252               CURLFORM_BUFFERLENGTH, record_length,
 253               CURLFORM_END);
 254
 255  /* no option needed for the end marker */
 256  curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
 257               CURLFORM_ARRAY, forms, CURLFORM_END);
 258  /* Add the content of a file as a normal post text value */
 259  curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
 260               CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
 261  /* Set the form info */
 262  curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
 263
 264 .SH "SEE ALSO"
 265 .BR curl_easy_setopt "(3),"
 266 .BR curl_formfree "(3),"
 267 .BR curl_mime_init "(3)"