| 1 |
.\" ************************************************************************** |
| 2 |
.\" * _ _ ____ _ |
| 3 |
.\" * Project ___| | | | _ \| | |
| 4 |
.\" * / __| | | | |_) | | |
| 5 |
.\" * | (__| |_| | _ <| |___ |
| 6 |
.\" * \___|\___/|_| \_\_____| |
| 7 |
.\" * |
| 8 |
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <[email protected]>, 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 "24 June 2002" "libcurl 7.9.8" "libcurl Manual" |
| 23 |
.SH NAME |
| 24 |
curl_formadd - add a section to a multipart/formdata HTTP POST |
| 25 |
.SH SYNOPSIS |
| 26 |
.B #include <curl/curl.h> |
| 27 |
.sp |
| 28 |
.BI "CURLFORMcode curl_formadd(struct curl_httppost ** " firstitem, |
| 29 |
.BI "struct curl_httppost ** " lastitem, " ...);" |
| 30 |
.ad |
| 31 |
.SH DESCRIPTION |
| 32 |
This function is deprecated. Do not use! See \fIcurl_mime_init(3)\fP instead! |
| 33 |
|
| 34 |
curl_formadd() is used to append sections when building a multipart/formdata |
| 35 |
HTTP POST (sometimes referred to as RFC2388-style posts). Append one section |
| 36 |
at a time until you've added all the sections you want included and then you |
| 37 |
pass the \fIfirstitem\fP pointer as parameter to \fICURLOPT_HTTPPOST(3)\fP. |
| 38 |
\fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated |
| 39 |
invokes it should be left as set to allow repeated invokes to find the end of |
| 40 |
the list faster. |
| 41 |
|
| 42 |
After the \fIlastitem\fP pointer follow the real arguments. |
| 43 |
|
| 44 |
The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to |
| 45 |
NULL in the first call to this function. All list-data will be allocated by |
| 46 |
the function itself. You must call \fIcurl_formfree(3)\fP on the |
| 47 |
\fIfirstitem\fP after the form post has been done to free the resources. |
| 48 |
|
| 49 |
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. |
| 50 |
You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. |
| 51 |
|
| 52 |
First, there are some basics you need to understand about multipart/formdata |
| 53 |
posts. Each part consists of at least a NAME and a CONTENTS part. If the part |
| 54 |
is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME. |
| 55 |
Below, we'll discuss what options you use to set these properties in the |
| 56 |
parts you want to add to your post. |
| 57 |
|
| 58 |
The options listed first are for making normal parts. The options from |
| 59 |
\fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload |
| 60 |
parts. |
| 61 |
.SH OPTIONS |
| 62 |
.IP CURLFORM_COPYNAME |
| 63 |
followed by a string which provides the \fIname\fP of this part. libcurl |
| 64 |
copies the string so your application doesn't need to keep it around after |
| 65 |
this function call. If the name isn't NUL-terminated, you must set its length |
| 66 |
with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to contain |
| 67 |
zero-valued bytes. The copied data will be freed by \fIcurl_formfree(3)\fP. |
| 68 |
.IP CURLFORM_PTRNAME |
| 69 |
followed by a string which provides the \fIname\fP of this part. libcurl |
| 70 |
will use the pointer and refer to the data in your application, so you |
| 71 |
must make sure it remains until curl no longer needs it. If the name |
| 72 |
isn't NUL-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP. |
| 73 |
The \fIname\fP is not allowed to contain zero-valued bytes. |
| 74 |
.IP CURLFORM_COPYCONTENTS |
| 75 |
followed by a pointer to the contents of this part, the actual data |
| 76 |
to send away. libcurl copies the provided data, so your application doesn't |
| 77 |
need to keep it around after this function call. If the data isn't null |
| 78 |
terminated, or if you'd like it to contain zero bytes, you must |
| 79 |
set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied |
| 80 |
data will be freed by \fIcurl_formfree(3)\fP. |
| 81 |
.IP CURLFORM_PTRCONTENTS |
| 82 |
followed by a pointer to the contents of this part, the actual data |
| 83 |
to send away. libcurl will use the pointer and refer to the data in your |
| 84 |
application, so you must make sure it remains until curl no longer needs it. |
| 85 |
If the data isn't NUL-terminated, or if you'd like it to contain zero bytes, |
| 86 |
you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP. |
| 87 |
.IP CURLFORM_CONTENTLEN |
| 88 |
followed by a curl_off_t value giving the length of the contents. Note that |
| 89 |
for \fICURLFORM_STREAM\fP contents, this option is mandatory. |
| 90 |
|
| 91 |
If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on |
| 92 |
the contents to figure out the size. If you really want to send a zero byte |
| 93 |
content then you must make sure strlen() on the data pointer returns zero. |
| 94 |
|
| 95 |
(Option added in 7.46.0) |
| 96 |
.IP CURLFORM_CONTENTSLENGTH |
| 97 |
(This option is deprecated. Use \fICURLFORM_CONTENTLEN\fP instead!) |
| 98 |
|
| 99 |
followed by a long giving the length of the contents. Note that for |
| 100 |
\fICURLFORM_STREAM\fP contents, this option is mandatory. |
| 101 |
|
| 102 |
If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on |
| 103 |
the contents to figure out the size. If you really want to send a zero byte |
| 104 |
content then you must make sure strlen() on the data pointer returns zero. |
| 105 |
.IP CURLFORM_FILECONTENT |
| 106 |
followed by a filename, causes that file to be read and its contents used |
| 107 |
as data in this part. This part does \fInot\fP automatically become a file |
| 108 |
upload part simply because its data was read from a file. |
| 109 |
|
| 110 |
The specified file needs to kept around until the associated transfer is done. |
| 111 |
.IP CURLFORM_FILE |
| 112 |
followed by a filename, makes this part a file upload part. It sets the |
| 113 |
\fIfilename\fP field to the basename of the provided filename, it reads the |
| 114 |
contents of the file and passes them as data and sets the content-type if the |
| 115 |
given file match one of the internally known file extensions. For |
| 116 |
\fBCURLFORM_FILE\fP the user may send one or more files in one part by |
| 117 |
providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename |
| 118 |
(and each \fICURLFORM_FILE\fP is allowed to have a |
| 119 |
\fICURLFORM_CONTENTTYPE\fP). |
| 120 |
|
| 121 |
The given upload file has to exist in its full in the file system already when |
| 122 |
the upload starts, as libcurl needs to read the correct file size beforehand. |
| 123 |
|
| 124 |
The specified file needs to kept around until the associated transfer is done. |
| 125 |
.IP CURLFORM_CONTENTTYPE |
| 126 |
is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a |
| 127 |
string which provides the content-type for this part, possibly instead of an |
| 128 |
internally chosen one. |
| 129 |
.IP CURLFORM_FILENAME |
| 130 |
is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a |
| 131 |
string, it tells libcurl to use the given string as the \fIfilename\fP in the |
| 132 |
file upload part instead of the actual file name. |
| 133 |
.IP CURLFORM_BUFFER |
| 134 |
is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It |
| 135 |
tells libcurl that the file contents are already present in a buffer. The |
| 136 |
parameter is a string which provides the \fIfilename\fP field in the content |
| 137 |
header. |
| 138 |
.IP CURLFORM_BUFFERPTR |
| 139 |
is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer |
| 140 |
to the buffer to be uploaded. This buffer must not be freed until after |
| 141 |
\fIcurl_easy_cleanup(3)\fP is called. You must also use |
| 142 |
\fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer. |
| 143 |
.IP CURLFORM_BUFFERLENGTH |
| 144 |
is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a |
| 145 |
long which gives the length of the buffer. |
| 146 |
.IP CURLFORM_STREAM |
| 147 |
Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get |
| 148 |
data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on |
| 149 |
to the read callback's fourth argument. If you want the part to look like a |
| 150 |
file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that |
| 151 |
when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be |
| 152 |
set with the total expected length of the part unless the formpost is sent |
| 153 |
chunked encoded. (Option added in libcurl 7.18.2) |
| 154 |
.IP CURLFORM_ARRAY |
| 155 |
Another possibility to send options to curl_formadd() is the |
| 156 |
\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as |
| 157 |
its value. Each curl_forms structure element has a CURLformoption and a char |
| 158 |
pointer. The final element in the array must be a CURLFORM_END. All available |
| 159 |
options can be used in an array, except the CURLFORM_ARRAY option itself! The |
| 160 |
last argument in such an array must always be \fBCURLFORM_END\fP. |
| 161 |
.IP CURLFORM_CONTENTHEADER |
| 162 |
specifies extra headers for the form POST section. This takes a curl_slist |
| 163 |
prepared in the usual way using \fBcurl_slist_append\fP and appends the list |
| 164 |
of headers to those libcurl automatically generates. The list must exist while |
| 165 |
the POST occurs, if you free it before the post completes you may experience |
| 166 |
problems. |
| 167 |
|
| 168 |
When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using |
| 169 |
the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after |
| 170 |
you've called \fIcurl_easy_cleanup(3)\fP for the curl handle. |
| 171 |
|
| 172 |
See example below. |
| 173 |
.SH AVAILABILITY |
| 174 |
Deprecated in 7.56.0. Before this release, field names were allowed to |
| 175 |
contain zero-valued bytes. The pseudo-filename "-" to read stdin is |
| 176 |
discouraged although still supported, but data is not read before being |
| 177 |
actually sent: the effective data size can then not be automatically |
| 178 |
determined, resulting in a chunked encoding transfer. Backslashes and |
| 179 |
double quotes in field and file names are now escaped before transmission. |
| 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)" |