diff --git a/docs/curl_formadd.3 b/docs/curl_formadd.3 index d16328817..b8912dbe1 100644 --- a/docs/curl_formadd.3 +++ b/docs/curl_formadd.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_formadd 3 "19 August 2001" "libcurl 7.9" "libcurl Manual" +.TH curl_formadd 3 "27 August 2001" "libcurl 7.9" "libcurl Manual" .SH NAME curl_formadd - add a section to a multipart/formdata HTTP POST .SH SYNOPSIS @@ -24,21 +24,22 @@ After \fIlastitem\fP follow the real arguments that constitute the new section (if the following description confuses you jump directly to the examples): -The first is always CURLFORM_COPYNAME followed by a string used for -the name of the section. +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). -Afterwards one may use one of three arguments: CURLFORM_COPYCONTENTS, -CURLFORM_PTRCONTENTS, or CURLFORM_FILE. followed by a char or void +The three options for providing values are: CURLFORM_COPYCONTENTS, +CURLFORM_PTRCONTENTS, or CURLFORM_FILE, followed by a char or void pointer (allowed for PTRCONTENTS). -The next argument may be CURLFORM_CONTENTTYPE if the +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) -For CURLFORM_PTRCONTENTS 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 COPYCONTENTS this is always done). +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 CURLFORM_FILE the user may send multiple files in one section by providing multiple CURLFORM_FILE arguments each followed by the filename @@ -52,13 +53,13 @@ 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 argument after CURLFORM_PTRCONTENTS and keep its own -version of it allocated until you call \fIcurl_formfree\fP. When +the arguments after CURLFORM_PTRNAME and CURLFORM_PTRCONTENTS 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 argument after -CURLFORM_PTRCONTENTS you must ensure that the pointer stays valid -until you call \fIcurl_form_free\fP and \fIcurl_easy_cleanup\fP. +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. See example below. .SH RETURN VALUE @@ -68,6 +69,8 @@ Returns non-zero if an error occurs. HttpPost* post = NULL; HttpPost* last = NULL; + char namebuffer[] = "name buffer"; + long namelength = strlen(namebuffer); char buffer[] = "test buffer"; char htmlbuffer[] = "test buffer"; long htmlbufferlength = strlen(htmlbuffer); @@ -84,8 +87,12 @@ Returns non-zero if an error occurs. CURLFORM_COPYCONTENTS, "", CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END); /* Add name/ptrcontent section */ - curl_formadd(&post, &past, CURLFORM_COPYNAME, "name_for_ptrcontent", + 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,