corrected return code, general cleanup

docs/curl_formadd.3

@@ -2,13 +2,13 @@
 .\" nroff -man [file]
 .\" $Id$
 .\"
-.TH curl_formadd 3 "27 August 2001" "libcurl 7.9" "libcurl Manual"
+.TH curl_formadd 3 "29 October 2001" "libcurl 7.9.1" "libcurl Manual"
 .SH NAME
 curl_formadd - add a section to a multipart/formdata HTTP POST
 .SH SYNOPSIS
 .B #include <curl/curl.h>
 .sp
-.BI "CURLcode curl_formadd(struct HttpPost ** " firstitem,
+.BI "int curl_formadd(struct HttpPost ** " firstitem,
 .BI "struct HttpPost ** " lastitem, " ...);"
 .ad
 .SH DESCRIPTION
@@ -17,62 +17,62 @@ 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 in a faster
-way.
+left as set to allow repeated invokes to find the end of the list faster.
 
-After \fIlastitem\fP follow the real arguments that constitute the
-new section (if the following description confuses you jump directly
-to the examples):
+After the \fIlastitem\fP pointer follow the real arguments. (If the following
+description confuses you, jump directly to the examples):
 
-CURLFORM_COPYNAME or CURLFORM_PTRNAME followed by a string is used for
-the name of the section. Optionally one may use CURLFORM_NAMELENGTH to
-specify the length of the name (allowing null characters within the name).
+\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 four options for providing values are: CURLFORM_COPYCONTENTS,
-CURLFORM_PTRCONTENTS, CURLFORM_FILE, or CURLFORM_FILECONTENT followed
-by a char or void pointer (allowed for PTRCONTENTS).
+The four options for providing values are: \fBCURLFORM_COPYCONTENTS\fP,
+\fBCURLFORM_PTRCONTENTS\fP, \fBCURLFORM_FILE\fP, or \fBCURLFORM_FILECONTENT\fP
+followed by a char or void pointer (allowed for PTRCONTENTS).
 
-CURLFORM_FILECONTENT does a normal post like CURLFORM_COPYCONTENTS but
-the actual value is read from the filename given as a string.
+\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 CURLFORM_CONTENTTYPE 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).
+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 CURLFORM_PTRCONTENTS or CURLFORM_COPYNAME the user may also add
-CURLFORM_CONTENTSLENGTH followed by the length as a long (if not given
-the library will use strlen to determine the length).
+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 CURLFORM_FILE the user may send multiple files in one section by
-providing multiple CURLFORM_FILE arguments each followed by the filename
+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).
 
-Another possibility to send single or multiple files in one section is
-to use CURLFORM_ARRAY that gets a struct curl_forms array as its
-value. Each structure element has a CURLformoption and a char
-pointer. For the options only CURLFORM_FILE, CURLFORM_CONTENTTYPE, and
-CURLFORM_END (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 CURLFORM_FILE options possibly with CURLFORM_CONTENTTYPE
-after or before each CURLFORM_FILE option.
+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.
 
-The last argument always is CURLFORM_END.
+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
 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 CURLFORM_PTRNAME and CURLFORM_PTRCONTENTS and keep
+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
-CURLFORM_PTRNAME or CURLFORM_PTRCONTENTS you must ensure that the pointer
-stays valid until you call \fIcurl_form_free\fP and \fIcurl_easy_cleanup\fP.
+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.
 
 See example below.
 .SH RETURN VALUE
@@ -98,39 +98,48 @@ Returns non-zero if an error occurs.
  /* Add simple name/content section */
  curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
               CURLFORM_COPYCONTENTS, "content", CURLFORM_END); 
+
  /* Add simple name/content/contenttype section */
  curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
               CURLFORM_COPYCONTENTS, "<HTML></HTML>",
               CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
+
  /* Add name/ptrcontent section */
  curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
               CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
+
  /* Add ptrname/ptrcontent section */
  curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
 	      CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
 	      namelength, CURLFORM_END);
+
  /* Add name/ptrcontent/contenttype section */
  curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
               CURLFORM_PTRCONTENTS, htmlbuffer,
               CURLFORM_CONTENTSLENGTH, htmlbufferlength,
               CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
+
  /* Add simple file section */
  curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
               CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
+
  /* Add file/contenttype section */
  curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
               CURLFORM_FILE, "my-face.jpg",
               CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
+
  /* Add two file section */
  curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
               CURLFORM_FILE, "my-face.jpg",
               CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
+
  /* Add two file section using CURLFORM_ARRAY */
  forms[0].option = CURLFORM_FILE;
  forms[0].value  = file1;
  forms[1].option = CURLFORM_FILE;
  forms[1].value  = file2;
- forms[2].value  = CURLFORM_END;
+ forms[2].option  = CURLFORM_END;
+
  /* no option needed for the end marker */
  curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
               CURLFORM_ARRAY, forms, CURLFORM_END);
@@ -143,7 +152,7 @@ Returns non-zero if an error occurs.
 .SH "SEE ALSO"
 .BR curl_easy_setopt "(3), "
 .BR curl_formparse "(3) [deprecated], "
-.BR curl_formfree "(3)
+.BR curl_formfree "(3)"
 .SH BUGS
 Surely there are some, you tell me!