-.\" You can view this file with:
-.\" nroff -man [file]
-.\" $Id$
-.\"
-.TH curl_formadd 3 "15 June 2002" "libcurl 7.9.8" "libcurl Manual"
+.\" **************************************************************************
+.\" * _ _ ____ _
+.\" * Project ___| | | | _ \| |
+.\" * / __| | | | |_) | |
+.\" * | (__| |_| | _ <| |___
+.\" * \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at http://curl.haxx.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" **************************************************************************
+.TH curl_formadd 3 "24 June 2002" "libcurl 7.9.8" "libcurl Manual"
.SH NAME
curl_formadd - add a section to a multipart/formdata HTTP POST
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
-.BI "CURLFORMcode curl_formadd(struct HttpPost ** " firstitem,
-.BI "struct HttpPost ** " lastitem, " ...);"
+.BI "CURLFORMcode curl_formadd(struct curl_httppost ** " firstitem,
+.BI "struct curl_httppost ** " lastitem, " ...);"
.ad
.SH DESCRIPTION
curl_formadd() is used to append sections when building a multipart/formdata
-HTTP POST (sometimes refered to as rfc1867-style posts). Append one section at
-a time until you've added all the sections you want included and then you pass
-the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP.
-\fIlastitem\fP is set after each call and on repeated invokes it should be
-left as set to allow repeated invokes to find the end of the list faster.
-
-After the \fIlastitem\fP pointer follow the real arguments. (If the following
-description confuses you, jump directly to the examples):
-
-\fBCURLFORM_COPYNAME\fP or \fBCURLFORM_PTRNAME\fP followed by a string is used
-for the name of the section. Optionally one may use \fBCURLFORM_NAMELENGTH\fP
-to specify the length of the name (allowing null characters within the
-name). All options that use the word COPY in their names copy the given
-contents, while the ones with PTR in their names simply points to the (static)
-data you must make sure remain until curl no longer needs it.
-
-The options for providing values are: \fBCURLFORM_COPYCONTENTS\fP,
-\fBCURLFORM_PTRCONTENTS\fP, \fBCURLFORM_FILE\fP, \fBCURLFORM_BUFFER\fP,
-or \fBCURLFORM_FILECONTENT\fP followed by a char or void pointer
-(allowed for PTRCONTENTS).
-
-\fBCURLFORM_FILECONTENT\fP does a normal post like \fBCURLFORM_COPYCONTENTS\fP
-but the actual value is read from the filename given as a string.
-
-Other arguments may be \fBCURLFORM_CONTENTTYPE\fP if the user wishes to
-specify one (for FILE if no type is given the library tries to provide the
-correct one; for CONTENTS no Content-Type is sent in this case).
-
-For \fBCURLFORM_PTRCONTENTS\fP or \fBCURLFORM_COPYNAME\fP the user may also
-add \fBCURLFORM_CONTENTSLENGTH\fP followed by the length as a long (if not
-given the library will use strlen to determine the length).
-
-For \fBCURLFORM_FILE\fP the user may send multiple files in one section by
-providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
-(and each FILE is allowed to have a CONTENTTYPE).
-
-\fBCURLFORM_BUFFER\fP
-tells libcurl that a buffer is to be used to upload data instead of using a
-file. The value of the next parameter is used as the value of the "filename"
-parameter in the content header.
-
-\fBCURLFORM_BUFFERPTR\fP
-tells libcurl that the address of the next parameter is a pointer to the buffer
-containing data to upload. The buffer containing this data must not be freed
-until after curl_easy_cleanup is called.
-
-\fBCURLFORM_BUFFERLENGTH\fP
-tells libcurl that the length of the buffer to upload is the value of the
-next parameter.
-
-Another possibility to send single or multiple files in one section is to use
-\fBCURLFORM_ARRAY\fP that gets a struct curl_forms array pointer as its
-value. Each structure element has a CURLformoption and a char pointer. For the
-options only \fBCURLFORM_FILE\fP, \fBCURLFORM_CONTENTTYPE\fP, and
-\fBCURLFORM_END\fP (that is used to determine the end of the array and thus
-must be the option of the last and no other element of the curl_forms array)
-are allowed. The effect of this parameter is the same as giving multiple
-\fBCURLFORM_FILE\fP options possibly with \fBCURLFORM_CONTENTTYPE\fP after or
-before each \fBCURLFORM_FILE\fP option.
-
-Should you need to specify extra headers for the form POST section, use
-\fBCURLFORM_CONTENTHEADER\fP. This takes a curl_slist prepared in the usual way
-using \fBcurl_slist_append\fP and appends the list of headers to those Curl
-automatically generates for \fBCURLFORM_CONTENTTYPE\fP and the content
-disposition. The list must exist while the POST occurs, if you free it before
-the post completes you may experience problems.
-
-The last argument in such an array must always be \fBCURLFORM_END\fP.
-
-The pointers \fI*firstitem\fP and \fI*lastitem\fP should both be pointing to
+HTTP POST (sometimes referred to as RFC2388-style posts). Append one section
+at a time until you've added all the sections you want included and then you
+pass the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST(3)\fP.
+\fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated
+invokes it should be left as set to allow repeated invokes to find the end of
+the list faster.
+
+After the \fIlastitem\fP pointer follow the real arguments.
+
+The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to
NULL in the first call to this function. All list-data will be allocated by
-the function itself. You must call \fIcurl_formfree\fP after the form post has
-been done to free the resources again.
-
-This function will copy all input data except the data pointed to by the
-arguments after \fBCURLFORM_PTRNAME\fP and \fBCURLFORM_PTRCONTENTS\fP and keep
-its own version of it allocated until you call \fIcurl_formfree\fP. When
-you've passed the pointer to \fIcurl_easy_setopt\fP, you must not free the
-list until after you've called \fIcurl_easy_cleanup\fP for the curl handle. If
-you provide a pointer as an arguments after \fBCURLFORM_PTRNAME\fP or
-\fBCURLFORM_PTRCONTENTS\fP you must ensure that the pointer stays valid until
-you call \fIcurl_form_free\fP and \fIcurl_easy_cleanup\fP.
+the function itself. You must call \fIcurl_formfree(3)\fP on the
+\fIfirstitem\fP after the form post has been done to free the resources.
+
+Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
+You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
+
+First, there are some basics you need to understand about multipart/formdata
+posts. Each part consists of at least a NAME and a CONTENTS part. If the part
+is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME.
+Below, we'll discuss what options you use to set these properties in the
+parts you want to add to your post.
+
+The options listed first are for making normal parts. The options from
+\fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload
+parts.
+.SH OPTIONS
+.IP CURLFORM_COPYNAME
+followed by a string which provides the \fIname\fP of this part. libcurl
+copies the string so your application doesn't need to keep it around after
+this function call. If the name isn't NUL-terminated, or if you'd
+like it to contain zero bytes, you must set its length with
+\fBCURLFORM_NAMELENGTH\fP. The copied data will be freed by
+\fIcurl_formfree(3)\fP.
+.IP CURLFORM_PTRNAME
+followed by a string which provides the \fIname\fP of this part. libcurl
+will use the pointer and refer to the data in your application, so you
+must make sure it remains until curl no longer needs it. If the name
+isn't NUL-terminated, or if you'd like it to contain zero
+bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP.
+.IP CURLFORM_COPYCONTENTS
+followed by a pointer to the contents of this part, the actual data
+to send away. libcurl copies the provided data, so your application doesn't
+need to keep it around after this function call. If the data isn't null
+terminated, or if you'd like it to contain zero bytes, you must
+set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied
+data will be freed by \fIcurl_formfree(3)\fP.
+.IP CURLFORM_PTRCONTENTS
+followed by a pointer to the contents of this part, the actual data
+to send away. libcurl will use the pointer and refer to the data in your
+application, so you must make sure it remains until curl no longer needs it.
+If the data isn't NUL-terminated, or if you'd like it to contain zero bytes,
+you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP.
+.IP CURLFORM_CONTENTSLENGTH
+followed by a long giving the length of the contents. Note that for
+\fICURLFORM_STREAM\fP contents, this option is mandatory.
+
+If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
+the contents to figure out the size. If you really want to send a zero byte
+content then you must make sure strlen() on the data pointer returns zero.
+.IP CURLFORM_FILECONTENT
+followed by a filename, causes that file to be read and its contents used
+as data in this part. This part does \fInot\fP automatically become a file
+upload part simply because its data was read from a file.
+.IP CURLFORM_FILE
+followed by a filename, makes this part a file upload part. It sets the
+\fIfilename\fP field to the basename of the provided filename, it reads the
+contents of the file and passes them as data and sets the content-type if the
+given file match one of the internally known file extensions. For
+\fBCURLFORM_FILE\fP the user may send one or more files in one part by
+providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
+(and each \fICURLFORM_FILE\fP is allowed to have a
+\fICURLFORM_CONTENTTYPE\fP).
+.IP CURLFORM_CONTENTTYPE
+is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
+string which provides the content-type for this part, possibly instead of an
+internally chosen one.
+.IP CURLFORM_FILENAME
+is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
+string, it tells libcurl to use the given string as the \fIfilename\fP in the
+file upload part instead of the actual file name.
+.IP CURLFORM_BUFFER
+is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It
+tells libcurl that the file contents are already present in a buffer. The
+parameter is a string which provides the \fIfilename\fP field in the content
+header.
+.IP CURLFORM_BUFFERPTR
+is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer
+to the buffer to be uploaded. This buffer must not be freed until after
+\fIcurl_easy_cleanup(3)\fP is called. You must also use
+\fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer.
+.IP CURLFORM_BUFFERLENGTH
+is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a
+long which gives the length of the buffer.
+.IP CURLFORM_STREAM
+Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get
+data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on
+to the read callback's fourth argument. If you want the part to look like a
+file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that
+when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be
+set with the total expected length of the part. (Option added in libcurl
+7.18.2)
+.IP CURLFORM_ARRAY
+Another possibility to send options to curl_formadd() is the
+\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
+its value. Each curl_forms structure element has a CURLformoption and a char
+pointer. The final element in the array must be a CURLFORM_END. All available
+options can be used in an array, except the CURLFORM_ARRAY option itself! The
+last argument in such an array must always be \fBCURLFORM_END\fP.
+.IP CURLFORM_CONTENTHEADER
+specifies extra headers for the form POST section. This takes a curl_slist
+prepared in the usual way using \fBcurl_slist_append\fP and appends the list
+of headers to those libcurl automatically generates. The list must exist while
+the POST occurs, if you free it before the post completes you may experience
+problems.
+
+When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
+the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after
+you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
See example below.
.SH RETURN VALUE
-0 means everything was ok, non-zero means an error occurred as
+0 means everything was ok, non-zero means an error occurred corresponding
+to a CURL_FORMADD_* constant defined in
.I <curl/curl.h>
-defines.
.SH EXAMPLE
.nf
- struct HttpPost* post = NULL;
- struct HttpPost* last = NULL;
+ struct curl_httppost* post = NULL;
+ struct curl_httppost* last = NULL;
char namebuffer[] = "name buffer";
long namelength = strlen(namebuffer);
char buffer[] = "test buffer";
/* Add simple name/content section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
- CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
+ CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
/* Add simple name/content/contenttype section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
/* Add ptrname/ptrcontent section */
curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
- CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
- namelength, CURLFORM_END);
+ CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
+ namelength, CURLFORM_END);
/* Add name/ptrcontent/contenttype section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
/* Add a buffer to upload */
curl_formadd(&post, &last,
+ CURLFORM_COPYNAME, "name",
CURLFORM_BUFFER, "data",
CURLFORM_BUFFERPTR, record,
CURLFORM_BUFFERLENGTH, record_length,
.SH "SEE ALSO"
.BR curl_easy_setopt "(3), "
-.BR curl_formparse "(3) [deprecated], "
.BR curl_formfree "(3)"
-.SH BUGS
-Surely there are some, you tell me!
-
projects / platform / upstream / curl.git / blobdiff