Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/curl/docs/libcurl/curl_formadd.3 @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 .\" **************************************************************************
2 .\" * _ _ ____ _
3 .\" * Project ___| | | | _ \| |
4 .\" * / __| | | | |_) | |
5 .\" * | (__| |_| | _ <| |___
6 .\" * \___|\___/|_| \_\_____|
7 .\" *
8 .\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
9 .\" *
10 .\" * This software is licensed as described in the file COPYING, which
11 .\" * you should have received as part of this distribution. The terms
12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
13 .\" *
14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
15 .\" * copies of the Software, and permit persons to whom the Software is
16 .\" * furnished to do so, under the terms of the COPYING file.
17 .\" *
18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19 .\" * KIND, either express or implied.
20 .\" *
21 .\" **************************************************************************
22 .TH curl_formadd 3 "24 June 2002" "libcurl 7.9.8" "libcurl Manual"
23 .SH NAME
24 curl_formadd - add a section to a multipart/formdata HTTP POST
25 .SH SYNOPSIS
26 .B #include <curl/curl.h>
27 .sp
28 .BI "CURLFORMcode curl_formadd(struct curl_httppost ** " firstitem,
29 .BI "struct curl_httppost ** " lastitem, " ...);"
30 .ad
31 .SH DESCRIPTION
32 This function is deprecated. Do not use! See \fIcurl_mime_init(3)\fP instead!
33
34 curl_formadd() is used to append sections when building a multipart/formdata
35 HTTP POST (sometimes referred to as RFC2388-style posts). Append one section
36 at a time until you've added all the sections you want included and then you
37 pass the \fIfirstitem\fP pointer as parameter to \fICURLOPT_HTTPPOST(3)\fP.
38 \fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated
39 invokes it should be left as set to allow repeated invokes to find the end of
40 the list faster.
41
42 After the \fIlastitem\fP pointer follow the real arguments.
43
44 The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to
45 NULL in the first call to this function. All list-data will be allocated by
46 the function itself. You must call \fIcurl_formfree(3)\fP on the
47 \fIfirstitem\fP after the form post has been done to free the resources.
48
49 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
50 You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
51
52 First, there are some basics you need to understand about multipart/formdata
53 posts. Each part consists of at least a NAME and a CONTENTS part. If the part
54 is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME.
55 Below, we'll discuss what options you use to set these properties in the
56 parts you want to add to your post.
57
58 The options listed first are for making normal parts. The options from
59 \fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload
60 parts.
61 .SH OPTIONS
62 .IP CURLFORM_COPYNAME
63 followed by a string which provides the \fIname\fP of this part. libcurl
64 copies the string so your application doesn't need to keep it around after
65 this function call. If the name isn't NUL-terminated, you must set its length
66 with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to contain
67 zero-valued bytes. The copied data will be freed by \fIcurl_formfree(3)\fP.
68 .IP CURLFORM_PTRNAME
69 followed by a string which provides the \fIname\fP of this part. libcurl
70 will use the pointer and refer to the data in your application, so you
71 must make sure it remains until curl no longer needs it. If the name
72 isn't NUL-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP.
73 The \fIname\fP is not allowed to contain zero-valued bytes.
74 .IP CURLFORM_COPYCONTENTS
75 followed by a pointer to the contents of this part, the actual data
76 to send away. libcurl copies the provided data, so your application doesn't
77 need to keep it around after this function call. If the data isn't null
78 terminated, or if you'd like it to contain zero bytes, you must
79 set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied
80 data will be freed by \fIcurl_formfree(3)\fP.
81 .IP CURLFORM_PTRCONTENTS
82 followed by a pointer to the contents of this part, the actual data
83 to send away. libcurl will use the pointer and refer to the data in your
84 application, so you must make sure it remains until curl no longer needs it.
85 If the data isn't NUL-terminated, or if you'd like it to contain zero bytes,
86 you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP.
87 .IP CURLFORM_CONTENTLEN
88 followed by a curl_off_t value giving the length of the contents. Note that
89 for \fICURLFORM_STREAM\fP contents, this option is mandatory.
90
91 If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
92 the contents to figure out the size. If you really want to send a zero byte
93 content then you must make sure strlen() on the data pointer returns zero.
94
95 (Option added in 7.46.0)
96 .IP CURLFORM_CONTENTSLENGTH
97 (This option is deprecated. Use \fICURLFORM_CONTENTLEN\fP instead!)
98
99 followed by a long giving the length of the contents. Note that for
100 \fICURLFORM_STREAM\fP contents, this option is mandatory.
101
102 If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
103 the contents to figure out the size. If you really want to send a zero byte
104 content then you must make sure strlen() on the data pointer returns zero.
105 .IP CURLFORM_FILECONTENT
106 followed by a filename, causes that file to be read and its contents used
107 as data in this part. This part does \fInot\fP automatically become a file
108 upload part simply because its data was read from a file.
109
110 The specified file needs to kept around until the associated transfer is done.
111 .IP CURLFORM_FILE
112 followed by a filename, makes this part a file upload part. It sets the
113 \fIfilename\fP field to the basename of the provided filename, it reads the
114 contents of the file and passes them as data and sets the content-type if the
115 given file match one of the internally known file extensions. For
116 \fBCURLFORM_FILE\fP the user may send one or more files in one part by
117 providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
118 (and each \fICURLFORM_FILE\fP is allowed to have a
119 \fICURLFORM_CONTENTTYPE\fP).
120
121 The given upload file has to exist in its full in the file system already when
122 the upload starts, as libcurl needs to read the correct file size beforehand.
123
124 The specified file needs to kept around until the associated transfer is done.
125 .IP CURLFORM_CONTENTTYPE
126 is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
127 string which provides the content-type for this part, possibly instead of an
128 internally chosen one.
129 .IP CURLFORM_FILENAME
130 is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
131 string, it tells libcurl to use the given string as the \fIfilename\fP in the
132 file upload part instead of the actual file name.
133 .IP CURLFORM_BUFFER
134 is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It
135 tells libcurl that the file contents are already present in a buffer. The
136 parameter is a string which provides the \fIfilename\fP field in the content
137 header.
138 .IP CURLFORM_BUFFERPTR
139 is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer
140 to the buffer to be uploaded. This buffer must not be freed until after
141 \fIcurl_easy_cleanup(3)\fP is called. You must also use
142 \fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer.
143 .IP CURLFORM_BUFFERLENGTH
144 is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a
145 long which gives the length of the buffer.
146 .IP CURLFORM_STREAM
147 Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get
148 data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on
149 to the read callback's fourth argument. If you want the part to look like a
150 file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that
151 when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be
152 set with the total expected length of the part unless the formpost is sent
153 chunked encoded. (Option added in libcurl 7.18.2)
154 .IP CURLFORM_ARRAY
155 Another possibility to send options to curl_formadd() is the
156 \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
157 its value. Each curl_forms structure element has a CURLformoption and a char
158 pointer. The final element in the array must be a CURLFORM_END. All available
159 options can be used in an array, except the CURLFORM_ARRAY option itself! The
160 last argument in such an array must always be \fBCURLFORM_END\fP.
161 .IP CURLFORM_CONTENTHEADER
162 specifies extra headers for the form POST section. This takes a curl_slist
163 prepared in the usual way using \fBcurl_slist_append\fP and appends the list
164 of headers to those libcurl automatically generates. The list must exist while
165 the POST occurs, if you free it before the post completes you may experience
166 problems.
167
168 When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
169 the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after
170 you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
171
172 See example below.
173 .SH AVAILABILITY
174 Deprecated in 7.56.0. Before this release, field names were allowed to
175 contain zero-valued bytes. The pseudo-filename "-" to read stdin is
176 discouraged although still supported, but data is not read before being
177 actually sent: the effective data size can then not be automatically
178 determined, resulting in a chunked encoding transfer. Backslashes and
179 double quotes in field and file names are now escaped before transmission.
180 .SH RETURN VALUE
181 0 means everything was ok, non-zero means an error occurred corresponding
182 to a CURL_FORMADD_* constant defined in
183 .I <curl/curl.h>
184 .SH EXAMPLE
185 .nf
186
187 struct curl_httppost* post = NULL;
188 struct curl_httppost* last = NULL;
189 char namebuffer[] = "name buffer";
190 long namelength = strlen(namebuffer);
191 char buffer[] = "test buffer";
192 char htmlbuffer[] = "<HTML>test buffer</HTML>";
193 long htmlbufferlength = strlen(htmlbuffer);
194 struct curl_forms forms[3];
195 char file1[] = "my-face.jpg";
196 char file2[] = "your-face.jpg";
197 /* add null character into htmlbuffer, to demonstrate that
198 transfers of buffers containing null characters actually work
199 */
200 htmlbuffer[8] = '\\0';
201
202 /* Add simple name/content section */
203 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
204 CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
205
206 /* Add simple name/content/contenttype section */
207 curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
208 CURLFORM_COPYCONTENTS, "<HTML></HTML>",
209 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
210
211 /* Add name/ptrcontent section */
212 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
213 CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
214
215 /* Add ptrname/ptrcontent section */
216 curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
217 CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
218 namelength, CURLFORM_END);
219
220 /* Add name/ptrcontent/contenttype section */
221 curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
222 CURLFORM_PTRCONTENTS, htmlbuffer,
223 CURLFORM_CONTENTSLENGTH, htmlbufferlength,
224 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
225
226 /* Add simple file section */
227 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
228 CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
229
230 /* Add file/contenttype section */
231 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
232 CURLFORM_FILE, "my-face.jpg",
233 CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
234
235 /* Add two file section */
236 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
237 CURLFORM_FILE, "my-face.jpg",
238 CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
239
240 /* Add two file section using CURLFORM_ARRAY */
241 forms[0].option = CURLFORM_FILE;
242 forms[0].value = file1;
243 forms[1].option = CURLFORM_FILE;
244 forms[1].value = file2;
245 forms[2].option = CURLFORM_END;
246
247 /* Add a buffer to upload */
248 curl_formadd(&post, &last,
249 CURLFORM_COPYNAME, "name",
250 CURLFORM_BUFFER, "data",
251 CURLFORM_BUFFERPTR, record,
252 CURLFORM_BUFFERLENGTH, record_length,
253 CURLFORM_END);
254
255 /* no option needed for the end marker */
256 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
257 CURLFORM_ARRAY, forms, CURLFORM_END);
258 /* Add the content of a file as a normal post text value */
259 curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
260 CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
261 /* Set the form info */
262 curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
263
264 .SH "SEE ALSO"
265 .BR curl_easy_setopt "(3),"
266 .BR curl_formfree "(3),"
267 .BR curl_mime_init "(3)"