mirror of
https://github.com/curl/curl.git
synced 2024-12-27 06:59:43 +08:00
73b9d7eb0f
I was reading curl_unescape(3) and I noticed that there was an extra
space after the open parenthesis in the SYNOPSIS; I removed the extra
space.
I also ran a few grep -r commands to find and remove extra spaces
after '(' in other files, and to find and replace uses of `T*' instead
of `T *'. Some of the instances of `T*` where unnecessary casts that I
removed.
I also fixed a comment that was misaligned in CURLMOPT_SOCKETFUNCTION.3.
And I fixed some formatting inconsistencies: in curl_unescape(3), all
function parameter were mentioned with bold text except length, that was
mentioned as 'length'; and, in curl_easy_unescape(3), all parameters
were mentioned in bold text except url that was italicised. Now they are
all mentioned in bold.
Documentation is not very consistent in how function parameter are
formatted: many pages italicise them, and others display them in bold
text; but I think it makes sense to at least be consistent with
formatting within the same page.
Closes #11027
270 lines
13 KiB
Groff
270 lines
13 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * Project ___| | | | _ \| |
|
|
.\" * / __| | | | |_) | |
|
|
.\" * | (__| |_| | _ <| |___
|
|
.\" * \___|\___/|_| \_\_____|
|
|
.\" *
|
|
.\" * Copyright (C) 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 https://curl.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
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
|
.\" *
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
.\" * KIND, either express or implied.
|
|
.\" *
|
|
.\" * SPDX-License-Identifier: curl
|
|
.\" *
|
|
.\" **************************************************************************
|
|
.TH curl_formadd 3 "24 June 2002" "libcurl" "libcurl"
|
|
.SH NAME
|
|
curl_formadd - add a section to a multipart form POST
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <curl/curl.h>
|
|
|
|
CURLFORMcode curl_formadd(struct curl_httppost **firstitem,
|
|
struct curl_httppost **lastitem, ...);
|
|
.fi
|
|
.SH DESCRIPTION
|
|
\fBThis function is deprecated.\fP Use \fIcurl_mime_init(3)\fP instead.
|
|
|
|
curl_formadd() is used to append sections when building a multipart form
|
|
post. Append one section at a time until you have added all the sections you
|
|
want included and then you 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.
|
|
|
|
After the \fIlastitem\fP pointer follow the real arguments.
|
|
|
|
The pointers \fIfirstitem\fP and \fIlastitem\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(3)\fP on the
|
|
\fIfirstitem\fP after the form post 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(3)\fP as usual.
|
|
|
|
First, there are some basics you need to understand about multipart form
|
|
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 FILENAME.
|
|
Below, we will discuss what options you use to set these properties in the
|
|
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 a string which provides the \fIname\fP of this part. libcurl
|
|
copies the string so your application does not need to keep it around after
|
|
this function call. If the name is not null-terminated, you must set its
|
|
length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to
|
|
contain zero-valued bytes. The copied data will be freed by
|
|
\fIcurl_formfree(3)\fP.
|
|
.IP CURLFORM_PTRNAME
|
|
followed by a string which provides the \fIname\fP of this part. 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 name
|
|
is not null-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP.
|
|
The \fIname\fP is not allowed to contain zero-valued bytes.
|
|
.IP CURLFORM_COPYCONTENTS
|
|
followed by a pointer to the contents of this part, the actual data
|
|
to send away. libcurl copies the provided data, so your application does not
|
|
need to keep it around after this function call. If the data is not null
|
|
terminated, or if you would like it to contain zero bytes, you must
|
|
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 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
|
|
is not null-terminated, or if you would 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.
|
|
|
|
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.
|
|
.IP CURLFORM_FILECONTENT
|
|
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
|
|
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
|
|
\fBCURLFORM_FILE\fP the user may send one or more files in one part by
|
|
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
|
|
internally chosen one.
|
|
.IP CURLFORM_FILENAME
|
|
is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
|
|
string, it tells libcurl to use the given string as the \fIfilename\fP in the
|
|
file upload part instead of the actual file name.
|
|
.IP CURLFORM_BUFFER
|
|
is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It
|
|
tells libcurl that the file contents are already present in a buffer. The
|
|
parameter is a string which provides the \fIfilename\fP field in the content
|
|
header.
|
|
.IP CURLFORM_BUFFERPTR
|
|
is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer
|
|
to the buffer to be uploaded. This buffer must not be freed until after
|
|
\fIcurl_easy_cleanup(3)\fP is called. You must also use
|
|
\fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer.
|
|
.IP CURLFORM_BUFFERLENGTH
|
|
is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a
|
|
long which gives the length of the buffer.
|
|
.IP CURLFORM_STREAM
|
|
Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get
|
|
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 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
|
|
its value. Each curl_forms structure element has a \fICURLformoption\fP and a
|
|
char pointer. The final element in the array must be a CURLFORM_END. All
|
|
available options can be used in an array, except the CURLFORM_ARRAY option
|
|
itself. The last argument in such an array must always be \fBCURLFORM_END\fP.
|
|
.IP CURLFORM_CONTENTHEADER
|
|
specifies extra headers for the form POST section. This takes a curl_slist
|
|
prepared in the usual way using \fBcurl_slist_append\fP and appends the list
|
|
of headers to those libcurl automatically generates. The list must exist while
|
|
the POST occurs, if you free it before the post completes you may experience
|
|
problems.
|
|
|
|
When you have passed the \fIstruct curl_httppost\fP pointer to
|
|
\fIcurl_easy_setopt(3)\fP (using the \fICURLOPT_HTTPPOST(3)\fP option), you
|
|
must not free the list until after you have called \fIcurl_easy_cleanup(3)\fP
|
|
for the curl handle.
|
|
|
|
See example below.
|
|
.SH EXAMPLE
|
|
.nf
|
|
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);
|
|
.SH AVAILABILITY
|
|
Deprecated in 7.56.0. Before this release, field names were allowed to
|
|
contain zero-valued bytes. The pseudo-filename "-" to read stdin is
|
|
discouraged although still supported, but data is not read before being
|
|
actually sent: the effective data size can then not be automatically
|
|
determined, resulting in a chunked encoding transfer. Backslashes and
|
|
double quotes in field and file names are now escaped before transmission.
|
|
.SH RETURN VALUE
|
|
0 means everything was OK, non-zero means an error occurred corresponding
|
|
to a CURL_FORMADD_* constant defined in
|
|
.I <curl/curl.h>
|
|
.SH "SEE ALSO"
|
|
.BR curl_easy_setopt "(3),"
|
|
.BR curl_formfree "(3),"
|
|
.BR curl_mime_init "(3)"
|