-.\" You can view this file with:
-.\" nroff -man [file]
-.\" $Id$
-.\"
+.\" **************************************************************************
+.\" * _ _ ____ _
+.\" * 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
.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.
+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 \fI*firstitem\fP and \fI*lastitem\fP should both be pointing to
+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.
+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 here, we'll discuss on what options you use to set these
-properties in the parts you want to add to your post.
+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
-.B CURLFORM_COPYNAME
-followed by string is used to set the name of this part. libcurl copies the
-given data, so your application doesn't need to keep it around after this
-function call. If the name isn't zero terminated properly, or if you'd like it
-to contain zero bytes, you need to set the length of the name with
-\fBCURLFORM_NAMELENGTH\fP.
-
-.B CURLFORM_PTRNAME
-followed by a string is used for the name of this part. libcurl will use the
-pointer and refer to the data in your application, you must make sure it
-remains until curl no longer needs it. If the name isn't zero terminated
-properly, or if you'd like it to contain zero bytes, you need to set the
-length of the name with \fBCURLFORM_NAMELENGTH\fP.
-
-.B CURLFORM_COPYCONTENTS
-followed by a string is used for the contents of this part, the actual data to
-send away. libcurl copies the given data, so your application doesn't need to
-keep it around after this function call. If the data isn't zero terminated
-properly, or if you'd like it to contain zero bytes, you need to set the
-length of the name with \fBCURLFORM_CONTENTSLENGTH\fP.
-
-.B CURLFORM_PTRCONTENTS
-followed by a string is used for the contents of this part, the actual data to
-send away. libcurl will use the pointer and refer to the data in your
-application, you must make sure it remains until curl no longer needs it. If
-the data isn't zero terminated properly, or if you'd like it to contain zero
-bytes, you need to set the length of the name with
-\fBCURLFORM_CONTENTSLENGTH\fP.
-
-.B CURLFORM_FILECONTENT
-followed by a file name, makes that file read and the contents will be used in
-as data in this part.
-
-.B CURLFORM_FILE
-followed by a file name, makes this part a file upload part. It sets the file
-name field to the actual file name used here, it gets the contents of the file
-and passes as data and sets the content-type if the given file match one of
-the new internally known file extension. 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 CURLFORM_FILE is allowed to
-have a CURLFORM_CONTENTTYPE).
-
-.B CURLFORM_CONTENTTYPE
-followed by a pointer to a string with a content-type will make curl use this
-given content-type for this file upload part, possibly instead of an
+.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.
-
-.B CURLFORM_FILENAME
-followed by a pointer to a string to a name, will make libcurl use the given
-name in the file upload part, intead of the actual file name given to
-\fICURLFORM_FILE\fP.
-
-.B BCURLFORM_BUFFER
-followed by a string, tells libcurl that a buffer is to be used to upload data
-instead of using a file. The given string is used as the value of the file
-name field in the content header.
-
-.B CURLFORM_BUFFERPTR
-followed by a pointer to a data area, tells libcurl the address of the buffer
-containing data to upload (as indicated with \fICURLFORM_BUFFER\fP). The
-buffer containing this data must not be freed until after
-\fIcurl_easy_cleanup(3)\fP is called.
-
-.B CURLFORM_BUFFERLENGTH
-followed by a long with the size of the \fICURLFORM_BUFFERPTR\fP data area,
-tells libcurl the length of the buffer to upload.
-
-.B CURLFORM_ARRAY
+.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.
-
-.B CURLFORM_CONTENTHEADER
+.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
problems.
When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
-the \fICURLOPT_HTTPPOST\fP option), you must not free the list until after
+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",
.SH "SEE ALSO"
.BR curl_easy_setopt "(3), "
-.BR curl_formparse "(3) [deprecated], "
.BR curl_formfree "(3)"
projects / platform / upstream / curl.git / blobdiff