aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPatrick Monnerat <patrick@monnerat.net>2017-10-08 16:15:23 +0100
committerPatrick Monnerat <patrick@monnerat.net>2017-10-08 16:15:23 +0100
commit14d6e207d35792e3e10a674b2e27cf2aa3370bf8 (patch)
tree8a16213e827e88242cb70f3616736808fa25f285
parentb2df2d47e58d1150f11ea2f42aac6b84fa7f4d00 (diff)
docs: clarify form/mime usage of non-regular data files.
-rw-r--r--docs/cmdline-opts/form.d6
-rw-r--r--docs/libcurl/curl_formadd.35
-rw-r--r--docs/libcurl/curl_mime_filedata.36
3 files changed, 12 insertions, 5 deletions
diff --git a/docs/cmdline-opts/form.d b/docs/cmdline-opts/form.d
index 232d30c07..4cc5f5a39 100644
--- a/docs/cmdline-opts/form.d
+++ b/docs/cmdline-opts/form.d
@@ -25,9 +25,9 @@ the form-field to which portrait.jpg will be the input:
curl -F profile=@portrait.jpg https://example.com/upload.cgi
To read content from stdin instead of a file, use - as the filename. This goes
-for both @ and < constructs. Unfortunately it does not support reading the
-file from a named pipe or similar, as it needs the full size before the
-transfer starts.
+for both @ and < constructs. For this case, as well as for others in which the
+full data size cannot be determined before the transfer starts (as named pipes
+or similar), data is transferred as chunks by HTTP and rejected by IMAP.
You can also tell curl what Content-Type to use by using 'type=', in a manner
similar to:
diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3
index 39a749b7c..de202aa47 100644
--- a/docs/libcurl/curl_formadd.3
+++ b/docs/libcurl/curl_formadd.3
@@ -172,7 +172,10 @@ you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
See example below.
.SH AVAILABILITY
Deprecated in 7.56.0. Before this release, field names were allowed to
-contain zero-valued bytes.
+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.
.SH RETURN VALUE
0 means everything was ok, non-zero means an error occurred corresponding
to a CURL_FORMADD_* constant defined in
diff --git a/docs/libcurl/curl_mime_filedata.3 b/docs/libcurl/curl_mime_filedata.3
index 9a57068de..f522d997f 100644
--- a/docs/libcurl/curl_mime_filedata.3
+++ b/docs/libcurl/curl_mime_filedata.3
@@ -36,7 +36,7 @@ data to a mime part.
\fIpart\fP is the part's to assign contents to.
\fIfilename\fP points to the nul-terminated file's path name. The pointer can
-be NULL to detach previous part contents settings. Filename storage can be
+be NULL to detach the previous part contents settings. Filename storage can be
safely be reused after this call.
As a side effect, the part's remote file name is set to the base name of the
@@ -47,6 +47,10 @@ The contents of the file is read during the file transfer in a streaming
manner to allow huge files to get transfered without using much memory. It
therefore requires that the file is kept intact during the entire request.
+If the file size cannot be determined before actually reading it (such as for
+a device or named pipe), the whole mime structure containing the part
+will be transferred as chunks by HTTP and rejected by IMAP.
+
Setting a part's contents twice is valid: only the value set by the last call
is retained.
.SH AVAILABILITY