-.\" You can view this file with:
-.\" nroff -man [file]
-.\"
+.\" **************************************************************************
+.\" * _ _ ____ _
+.\" * 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 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\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(3)\fP after the form post
-has been done to free the resources.
+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\fP as usual.
+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
.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
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\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)
+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
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.
projects / external / curl.git / blobdiff