From 14d6e207d35792e3e10a674b2e27cf2aa3370bf8 Mon Sep 17 00:00:00 2001 From: Patrick Monnerat Date: Sun, 8 Oct 2017 16:15:23 +0100 Subject: [PATCH] docs: clarify form/mime usage of non-regular data files. --- docs/cmdline-opts/form.d | 6 +++--- docs/libcurl/curl_formadd.3 | 5 ++++- docs/libcurl/curl_mime_filedata.3 | 6 +++++- 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