<title>curl_formadd man page</title>
<meta name="generator" content="roffit">
<STYLE type="text/css">
-P.level0 {
+pre {
+ overflow: auto;
+ margin: 0;
+}
+
+P.level0, pre.level0 {
padding-left: 2em;
}
-P.level1 {
+P.level1, pre.level1 {
padding-left: 4em;
}
-P.level2 {
+P.level2, pre.level2 {
padding-left: 6em;
}
<p class="level1">followed by a pointer to the contents of this part, the actual data to send away. libcurl copies the provided data, so your application doesn't need to keep it around after this function call. If the data isn't null terminated, or if you'd like it to contain zero bytes, you must set the length of the name with <a class="bold" href="#CURLFORMCONTENTSLENGTH">CURLFORM_CONTENTSLENGTH</a>. The copied data will be freed by <a Class="emphasis" href="./curl_formfree.html">curl_formfree</a>.
<p class="level0"><a name="CURLFORMPTRCONTENTS"></a><span class="nroffip">CURLFORM_PTRCONTENTS</span>
<p class="level1">followed by a pointer to the contents of this part, the actual data 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 <a class="bold" href="#CURLFORMCONTENTSLENGTH">CURLFORM_CONTENTSLENGTH</a>.
+<p class="level0"><a name="CURLFORMCONTENTLEN"></a><span class="nroffip">CURLFORM_CONTENTLEN</span>
+<p class="level1">followed by a curl_off_t value giving the length of the contents. Note that for <a class="emphasis" href="#CURLFORMSTREAM">CURLFORM_STREAM</a> contents, this option is mandatory.
+<p class="level1">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.
+<p class="level1">(Option added in 7.46.0)
<p class="level0"><a name="CURLFORMCONTENTSLENGTH"></a><span class="nroffip">CURLFORM_CONTENTSLENGTH</span>
+<p class="level1">(This option is deprecated. Use <a class="emphasis" href="#CURLFORMCONTENTLEN">CURLFORM_CONTENTLEN</a> instead!)
<p class="level1">followed by a long giving the length of the contents. Note that for <a class="emphasis" href="#CURLFORMSTREAM">CURLFORM_STREAM</a> contents, this option is mandatory.
<p class="level1">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.
<p class="level0"><a name="CURLFORMFILECONTENT"></a><span class="nroffip">CURLFORM_FILECONTENT</span>
<p class="level1">followed by a filename, causes that file to be read and its contents used as data in this part. This part does <span Class="emphasis">not</span> automatically become a file upload part simply because its data was read from a file.
<p class="level0"><a name="CURLFORMFILE"></a><span class="nroffip">CURLFORM_FILE</span>
<p class="level1">followed by a filename, makes this part a file upload part. It sets the <span Class="emphasis">filename</span> field to the basename of the provided filename, it reads the contents of the file and passes them as data and sets the content-type if the given file match one of the internally known file extensions. For <a class="bold" href="#CURLFORMFILE">CURLFORM_FILE</a> the user may send one or more files in one part by providing multiple <a class="bold" href="#CURLFORMFILE">CURLFORM_FILE</a> arguments each followed by the filename (and each <a class="emphasis" href="#CURLFORMFILE">CURLFORM_FILE</a> is allowed to have a <a class="emphasis" href="#CURLFORMCONTENTTYPE">CURLFORM_CONTENTTYPE</a>).
+<p class="level1">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.
<p class="level0"><a name="CURLFORMCONTENTTYPE"></a><span class="nroffip">CURLFORM_CONTENTTYPE</span>
<p class="level1">is used in combination with <a class="emphasis" href="#CURLFORMFILE">CURLFORM_FILE</a>. Followed by a pointer to a string which provides the content-type for this part, possibly instead of an internally chosen one.
<p class="level0"><a name="CURLFORMFILENAME"></a><span class="nroffip">CURLFORM_FILENAME</span>
<p class="level1">When you've passed the HttpPost pointer to <a Class="emphasis" href="./curl_easy_setopt.html">curl_easy_setopt</a> (using the <span Class="emphasis">CURLOPT_HTTPPOST(3)</span> option), you must not free the list until after you've called <a Class="emphasis" href="./curl_easy_cleanup.html">curl_easy_cleanup</a> for the curl handle.
<p class="level1">See example below. <a name="RETURN"></a><h2 class="nroffsh">RETURN VALUE</h2>
<p class="level0">0 means everything was ok, non-zero means an error occurred corresponding to a CURL_FORMADD_* constant defined in <span Class="emphasis"><curl/curl.h></span> <a name="EXAMPLE"></a><h2 class="nroffsh">EXAMPLE</h2>
-<p class="level0"><pre>
-<p class="level0"><p class="level0"> struct curl_httppost* post = NULL;
- struct curl_httppost* last = NULL;
- char namebuffer[] = "name buffer";
- long namelength = strlen(namebuffer);
- char buffer[] = "test buffer";
- char htmlbuffer[] = "<HTML>test buffer</HTML>";
- long htmlbufferlength = strlen(htmlbuffer);
- struct curl_forms forms[3];
- char file1[] = "my-face.jpg";
- char file2[] = "your-face.jpg";
- /* add null character into htmlbuffer, to demonstrate that
- transfers of buffers containing null characters actually work
- */
- htmlbuffer[8] = '\0';
- <p class="level0"> /* Add simple name/content section */
- curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
- CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
- <p class="level0"> /* Add simple name/content/contenttype section */
- curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
- CURLFORM_COPYCONTENTS, "<HTML></HTML>",
- CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
- <p class="level0"> /* Add name/ptrcontent section */
- curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
- CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
- <p class="level0"> /* Add ptrname/ptrcontent section */
- curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
- CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
- namelength, CURLFORM_END);
- <p class="level0"> /* 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);
- <p class="level0"> /* Add simple file section */
- curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
- CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
- <p class="level0"> /* Add file/contenttype section */
- curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
- CURLFORM_FILE, "my-face.jpg",
- CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
- <p class="level0"> /* Add two file section */
- curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
- CURLFORM_FILE, "my-face.jpg",
- CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
- <p class="level0"> /* 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].option = CURLFORM_END;
- <p class="level0"> /* Add a buffer to upload */
- curl_formadd(&post, &last,
- CURLFORM_COPYNAME, "name",
- CURLFORM_BUFFER, "data",
- CURLFORM_BUFFERPTR, record,
- CURLFORM_BUFFERLENGTH, record_length,
- CURLFORM_END);
- <p class="level0"> /* no option needed for the end marker */
- curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
- CURLFORM_ARRAY, forms, CURLFORM_END);
- /* Add the content of a file as a normal post text value */
- curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
- CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
- /* Set the form info */
- curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
- <p class="level0"></pre>
+<p class="level0"><pre class="level0">
+
+ struct curl_httppost* post = NULL;
+ struct curl_httppost* last = NULL;
+ char namebuffer[] = "name buffer";
+ long namelength = strlen(namebuffer);
+ char buffer[] = "test buffer";
+ char htmlbuffer[] = "<HTML>test buffer</HTML>";
+ long htmlbufferlength = strlen(htmlbuffer);
+ struct curl_forms forms[3];
+ char file1[] = "my-face.jpg";
+ char file2[] = "your-face.jpg";
+ /* add null character into htmlbuffer, to demonstrate that
+ transfers of buffers containing null characters actually work
+ */
+ htmlbuffer[8] = '\0';
+
+ /* 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].option = CURLFORM_END;
+
+ /* Add a buffer to upload */
+ curl_formadd(&post, &last,
+ CURLFORM_COPYNAME, "name",
+ CURLFORM_BUFFER, "data",
+ CURLFORM_BUFFERPTR, record,
+ CURLFORM_BUFFERLENGTH, record_length,
+ CURLFORM_END);
+
+ /* no option needed for the end marker */
+ curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
+ CURLFORM_ARRAY, forms, CURLFORM_END);
+ /* Add the content of a file as a normal post text value */
+ curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
+ CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
+ /* Set the form info */
+ curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
+
+</pre>
<a name="SEE"></a><h2 class="nroffsh">SEE ALSO</h2>
-<p class="level0"><a Class="manpage" href="./curl_easy_setopt.html">curl_easy_setopt</a>, <
span Class="manpage"> </span> <a Class="manpage" href="./curl_formfree.html">curl_formfree</a>, <p class="roffit">
+<p class="level0"><a Class="manpage" href="./curl_easy_setopt.html">curl_easy_setopt</a>, <
a Class="manpage" href="./curl_formfree.html">curl_formfree</a><p class="roffit">
This HTML page was made with <a href="http://daniel.haxx.se/projects/roffit/">roffit</a>.
</body></html>
projects / platform / upstream / curl.git / blobdiff