| 1 |
Long: form |
| 2 |
Short: F |
| 3 |
Arg: <name=content> |
| 4 |
Help: Specify multipart MIME data |
| 5 |
Protocols: HTTP SMTP IMAP |
| 6 |
Mutexed: data head upload-file |
| 7 |
--- |
| 8 |
For HTTP protocol family, this lets curl emulate a filled-in form in which a |
| 9 |
user has pressed the submit button. This causes curl to POST data using the |
| 10 |
Content-Type multipart/form-data according to RFC 2388. |
| 11 |
|
| 12 |
For SMTP and IMAP protocols, this is the mean to compose a multipart mail |
| 13 |
message to transmit. |
| 14 |
|
| 15 |
This enables uploading of binary files etc. To force the 'content' part to be |
| 16 |
a file, prefix the file name with an @ sign. To just get the content part from |
| 17 |
a file, prefix the file name with the symbol <. The difference between @ and < |
| 18 |
is then that @ makes a file get attached in the post as a file upload, while |
| 19 |
the < makes a text field and just get the contents for that text field from a |
| 20 |
file. |
| 21 |
|
| 22 |
Tell curl to read content from stdin instead of a file by using - as |
| 23 |
filename. This goes for both @ and < constructs. When stdin is used, the |
| 24 |
contents is buffered in memory first by curl to determine its size and allow a |
| 25 |
possible resend. Defining a part's data from a named non-regular file (such |
| 26 |
as a named pipe or similar) is unfortunately not subject to buffering and will |
| 27 |
be effectively read at transmission time; since the full size is unknown |
| 28 |
before the transfer starts, such data is sent as chunks by HTTP and rejected |
| 29 |
by IMAP. |
| 30 |
|
| 31 |
Example: send an image to an HTTP server, where \&'profile' is the name of the |
| 32 |
form-field to which the file portrait.jpg will be the input: |
| 33 |
|
| 34 |
curl -F [email protected] https://example.com/upload.cgi |
| 35 |
|
| 36 |
Example: send your name and shoe size in two text fields to the server: |
| 37 |
|
| 38 |
curl -F name=John -F shoesize=11 https://example.com/ |
| 39 |
|
| 40 |
Example: send your essay in a text field to the server. Send it as a plain |
| 41 |
text field, but get the contents for it from a local file: |
| 42 |
|
| 43 |
curl -F "story=<hugefile.txt" https://example.com/ |
| 44 |
|
| 45 |
You can also tell curl what Content-Type to use by using 'type=', in a manner |
| 46 |
similar to: |
| 47 |
|
| 48 |
curl -F "[email protected];type=text/html" example.com |
| 49 |
|
| 50 |
or |
| 51 |
|
| 52 |
curl -F "name=daniel;type=text/foo" example.com |
| 53 |
|
| 54 |
You can also explicitly change the name field of a file upload part by setting |
| 55 |
filename=, like this: |
| 56 |
|
| 57 |
curl -F "file=@localfile;filename=nameinpost" example.com |
| 58 |
|
| 59 |
If filename/path contains ',' or ';', it must be quoted by double-quotes like: |
| 60 |
|
| 61 |
curl -F "file=@\\"localfile\\";filename=\\"nameinpost\\"" example.com |
| 62 |
|
| 63 |
or |
| 64 |
|
| 65 |
curl -F 'file=@"localfile";filename="nameinpost"' example.com |
| 66 |
|
| 67 |
Note that if a filename/path is quoted by double-quotes, any double-quote |
| 68 |
or backslash within the filename must be escaped by backslash. |
| 69 |
|
| 70 |
Quoting must also be applied to non-file data if it contains semicolons, |
| 71 |
leading/trailing spaces or leading double quotes: |
| 72 |
|
| 73 |
curl -F 'colors="red; green; blue";type=text/x-myapp' example.com |
| 74 |
|
| 75 |
You can add custom headers to the field by setting headers=, like |
| 76 |
|
| 77 |
curl -F "submit=OK;headers=\\"X-submit-type: OK\\"" example.com |
| 78 |
|
| 79 |
or |
| 80 |
|
| 81 |
curl -F "submit=OK;headers=@headerfile" example.com |
| 82 |
|
| 83 |
The headers= keyword may appear more that once and above notes about quoting |
| 84 |
apply. When headers are read from a file, Empty lines and lines starting |
| 85 |
with '#' are comments and ignored; each header can be folded by splitting |
| 86 |
between two words and starting the continuation line with a space; embedded |
| 87 |
carriage-returns and trailing spaces are stripped. |
| 88 |
Here is an example of a header file contents: |
| 89 |
|
| 90 |
# This file contain two headers. |
| 91 |
.br |
| 92 |
X-header-1: this is a header |
| 93 |
|
| 94 |
# The following header is folded. |
| 95 |
.br |
| 96 |
X-header-2: this is |
| 97 |
.br |
| 98 |
another header |
| 99 |
|
| 100 |
|
| 101 |
To support sending multipart mail messages, the syntax is extended as follows: |
| 102 |
.br |
| 103 |
- name can be omitted: the equal sign is the first character of the argument, |
| 104 |
.br |
| 105 |
- if data starts with '(', this signals to start a new multipart: it can be |
| 106 |
followed by a content type specification. |
| 107 |
.br |
| 108 |
- a multipart can be terminated with a '=)' argument. |
| 109 |
|
| 110 |
Example: the following command sends an SMTP mime e-mail consisting in an |
| 111 |
inline part in two alternative formats: plain text and HTML. It attaches a |
| 112 |
text file: |
| 113 |
|
| 114 |
curl -F '=(;type=multipart/alternative' \\ |
| 115 |
.br |
| 116 |
-F '=plain text message' \\ |
| 117 |
.br |
| 118 |
-F '= <body>HTML message</body>;type=text/html' \\ |
| 119 |
.br |
| 120 |
-F '=)' -F '[email protected]' ... smtp://example.com |
| 121 |
|
| 122 |
Data can be encoded for transfer using encoder=. Available encodings are |
| 123 |
\fIbinary\fP and \fI8bit\fP that do nothing else than adding the corresponding |
| 124 |
Content-Transfer-Encoding header, \fI7bit\fP that only rejects 8-bit characters |
| 125 |
with a transfer error, \fIquoted-printable\fP and \fIbase64\fP that encodes |
| 126 |
data according to the corresponding schemes, limiting lines length to |
| 127 |
76 characters. |
| 128 |
|
| 129 |
Example: send multipart mail with a quoted-printable text message and a |
| 130 |
base64 attached file: |
| 131 |
|
| 132 |
curl -F '=text message;encoder=quoted-printable' \\ |
| 133 |
.br |
| 134 |
-F '=@localfile;encoder=base64' ... smtp://example.com |
| 135 |
|
| 136 |
See further examples and details in the MANUAL. |
| 137 |
|
| 138 |
This option can be used multiple times. |