Mohun Biswas' improvements and clarifications about the options and how to use

them.

docs/libcurl/curl_formadd.3

@@ -23,88 +23,96 @@ After the \fIlastitem\fP pointer follow the real arguments.
 
 The pointers \fI*firstitem\fP and \fI*lastitem\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
+the function itself. You must call \fIcurl_formfree(3)\fP after the form post
-been done to free the resources again.
+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.
 
 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
+is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME.
-FILENAME. Below here, we'll discuss on what options you use to set these
+Below, we'll discuss what options you use to set these properties in the
-properties in the parts you want to add to your post.
+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 string is used to set the name of this part. libcurl copies the
+followed by a string which provides the \fIname\fP of this part. libcurl
-given data, so your application doesn't need to keep it around after this
+copies the string so your application doesn't need to keep it around after
-function call. If the name isn't zero terminated properly, or if you'd like it
+this function call. If the name isn't null terminated, or if you'd
-to contain zero bytes, you need to set the length of the name with
+like it to contain zero bytes, you must set its length with
-\fBCURLFORM_NAMELENGTH\fP.
+\fBCURLFORM_NAMELENGTH\fP. The copied data will be freed by
+\fIcurl_formfree(3)\fP.
 
 .IP CURLFORM_PTRNAME
-followed by a string is used for the name of this part. libcurl will use the
+followed by a string which provides the \fIname\fP of this part. libcurl
-pointer and refer to the data in your application, you must make sure it
+will use the pointer and refer to the data in your application, so you
-remains until curl no longer needs it. If the name isn't zero terminated
+must make sure it remains until curl no longer needs it. If the name
-properly, or if you'd like it to contain zero bytes, you need to set the
+isn't null terminated, or if you'd like it to contain zero
-length of the name with \fBCURLFORM_NAMELENGTH\fP.
+bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP.
 
 .IP CURLFORM_COPYCONTENTS
-followed by a string is used for the contents of this part, the actual data to
+followed by a pointer to the contents of this part, the actual data
-send away. libcurl copies the given data, so your application doesn't need to
+to send away. libcurl copies the provided data, so your application doesn't
-keep it around after this function call. If the data isn't zero terminated
+need to keep it around after this function call. If the data isn't null
-properly, or if you'd like it to contain zero bytes, you need to set the
+terminated, or if you'd like it to contain zero bytes, you must
-length of the name with \fBCURLFORM_CONTENTSLENGTH\fP.
+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 string is used for the contents of this part, the actual data to
+followed by a pointer to the contents of this part, the actual data
-send away. libcurl will use the pointer and refer to the data in your
+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
+application, so you must make sure it remains until curl no longer needs it.
-the data isn't zero terminated properly, or if you'd like it to contain zero
+If the data isn't null terminated, or if you'd like it to contain zero bytes,
-bytes, you need to set the length of the name with
+you must set its length  with \fBCURLFORM_CONTENTSLENGTH\fP.
-\fBCURLFORM_CONTENTSLENGTH\fP.
 
 .IP CURLFORM_CONTENTSLENGTH
-followed by a long setting the length of the contents.
+followed by a long giving the length of the contents.
 
 .IP CURLFORM_FILECONTENT
-followed by a file name, makes that file read and the contents will be used in
+followed by a filename, causes that file to be read and its contents used
-as data in this part.
+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 file name, makes this part a file upload part. It sets the file
+followed by a filename, makes this part a file upload part. It sets the
-name field to the actual file name used here, it gets the contents of the file
+\fIfilename\fP field to the basename of the provided filename, it reads the
-and passes as data and sets the content-type if the given file match one of
+contents of the file and passes them as data and sets the content-type if the
-the new internally known file extension.  For \fBCURLFORM_FILE\fP the user may
+given file match one of the internally known file extensions.  For
-send one or more files in one part by providing multiple \fBCURLFORM_FILE\fP
+\fBCURLFORM_FILE\fP the user may send one or more files in one part by
-arguments each followed by the filename (and each CURLFORM_FILE is allowed to
+providing multiple \fBCURLFORM_FILE\fP arguments each followed by the
-have a CURLFORM_CONTENTTYPE).
+filename (and each CURLFORM_FILE is allowed to have a CURLFORM_CONTENTTYPE).
 
 .IP CURLFORM_CONTENTTYPE
-followed by a pointer to a string with a content-type will make curl use this
+is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
-given content-type for this file upload part, possibly instead of an
+string which provides the content-type for this part, possibly instead of an
 internally chosen one.
 
 .IP CURLFORM_FILENAME
-followed by a pointer to a string to a name, will make libcurl use the given
+is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
-name in the file upload part, instead of the actual file name given to
+string, it tells libcurl to use the given string as the \fIfilename\fP in the
-\fICURLFORM_FILE\fP.
+file upload part instead of the actual file name.
 
 .IP CURLFORM_BUFFER
-followed by a string, tells libcurl that a buffer is to be used to upload data
+is used for custom file upload parts without use of \fICURLFORM_FILE\fP.  It
-instead of using a file. The given string is used as the value of the file
+tells libcurl that the file contents are already present in a buffer.  The
-name field in the content header.
+parameter is a string which provides the \fIfilename\fP field in the content
+header.
 
 .IP CURLFORM_BUFFERPTR
-followed by a pointer to a data area, tells libcurl the address of the buffer
+is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer
-containing data to upload (as indicated with \fICURLFORM_BUFFER\fP). The
+to the buffer to be uploaded. This buffer must not be freed until after
-buffer containing this data must not be freed until after
 \fIcurl_easy_cleanup(3)\fP is called. You must also use
-\fICURLFORM_BUFFERLENGTH\fP to set the length of the given buffer area.
+\fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer.
 
 .IP CURLFORM_BUFFERLENGTH
-followed by a long with the size of the \fICURLFORM_BUFFERPTR\fP data area,
+is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a
-tells libcurl the length of the buffer to upload.
+long which gives the length of the buffer.
 
 .IP CURLFORM_ARRAY
 Another possibility to send options to curl_formadd() is the