Imported Upstream version 7.53.1

[platform/upstream/curl.git] / docs / libcurl / curl_formadd.3

diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3
index 3e48149..5d1faa5 100644 (file)
--- a/docs/libcurl/curl_formadd.3
+++ b/docs/libcurl/curl_formadd.3
@@ -5,11 +5,11 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2016, 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.
+.\" * are also available at https://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
@@ -32,7 +32,7 @@ curl_formadd - add a section to a multipart/formdata HTTP POST
 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(3)\fP.
+pass the \fIfirstitem\fP pointer as parameter to \fICURLOPT_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.
@@ -83,7 +83,18 @@ 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_CONTENTLEN
+followed by a curl_off_t value 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.
+
+(Option added in 7.46.0)
 .IP CURLFORM_CONTENTSLENGTH
+(This option is deprecated. Use \fICURLFORM_CONTENTLEN\fP instead!)
+
 followed by a long giving the length of the contents. Note that for
 \fICURLFORM_STREAM\fP contents, this option is mandatory.
 
@@ -94,6 +105,8 @@ content then you must make sure strlen() on the data pointer returns zero.
 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.
+
+The specified file needs to kept around until the associated transfer is done.
 .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
@@ -103,6 +116,11 @@ given file match one of the internally known file extensions.  For
 providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
 (and each \fICURLFORM_FILE\fP is allowed to have a
 \fICURLFORM_CONTENTTYPE\fP).
+
+The given upload file has to exist in its full in the file system already when
+the upload starts, as libcurl needs to read the correct file size beforehand.
+
+The specified file needs to kept around until the associated transfer is done.
 .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
@@ -130,8 +148,8 @@ 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)
+set with the total expected length of the part unless the formpost is sent
+chunked encoded. (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