summaryrefslogtreecommitdiff
path: root/docs/cmdline-opts/form.d
blob: 3cd8dce756de49bd7ad957e54be41ea0d5a3cefb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
Long: form
Short: F
Arg: <name=content>
Help: Specify multipart MIME data
Protocols: HTTP SMTP IMAP
Mutexed: data head upload-file
Category: http upload
---
For HTTP protocol family, this lets curl emulate a filled-in form in which a
user has pressed the submit button. This causes curl to POST data using the
Content-Type multipart/form-data according to RFC 2388.

For SMTP and IMAP protocols, this is the mean to compose a multipart mail
message to transmit.

This enables uploading of binary files etc. To force the 'content' part to be
a file, prefix the file name with an @ sign. To just get the content part from
a file, prefix the file name with the symbol <. The difference between @ and <
is then that @ makes a file get attached in the post as a file upload, while
the < makes a text field and just get the contents for that text field from a
file.

Tell curl to read content from stdin instead of a file by using - as
filename. This goes for both @ and < constructs. When stdin is used, the
contents is buffered in memory first by curl to determine its size and allow a
possible resend.  Defining a part's data from a named non-regular file (such
as a named pipe or similar) is unfortunately not subject to buffering and will
be effectively read at transmission time; since the full size is unknown
before the transfer starts, such data is sent as chunks by HTTP and rejected
by IMAP.

Example: send an image to an HTTP server, where \&'profile' is the name of the
form-field to which the file portrait.jpg will be the input:

 curl -F profile=@portrait.jpg https://example.com/upload.cgi

Example: send your name and shoe size in two text fields to the server:

 curl -F name=John -F shoesize=11 https://example.com/

Example: send your essay in a text field to the server. Send it as a plain
text field, but get the contents for it from a local file:

 curl -F "story=<hugefile.txt" https://example.com/

You can also tell curl what Content-Type to use by using 'type=', in a manner
similar to:

 curl -F "web=@index.html;type=text/html" example.com

or

 curl -F "name=daniel;type=text/foo" example.com

You can also explicitly change the name field of a file upload part by setting
filename=, like this:

 curl -F "file=@localfile;filename=nameinpost" example.com

If filename/path contains ',' or ';', it must be quoted by double-quotes like:

 curl -F "file=@\\"localfile\\";filename=\\"nameinpost\\"" example.com

or

 curl -F 'file=@"localfile";filename="nameinpost"' example.com

Note that if a filename/path is quoted by double-quotes, any double-quote
or backslash within the filename must be escaped by backslash.

Quoting must also be applied to non-file data if it contains semicolons,
leading/trailing spaces or leading double quotes:

 curl -F 'colors="red; green; blue";type=text/x-myapp' example.com

You can add custom headers to the field by setting headers=, like

  curl -F "submit=OK;headers=\\"X-submit-type: OK\\"" example.com

or

  curl -F "submit=OK;headers=@headerfile" example.com

The headers= keyword may appear more that once and above notes about quoting
apply. When headers are read from a file, Empty lines and lines starting
with '#' are comments and ignored; each header can be folded by splitting
between two words and starting the continuation line with a space; embedded
carriage-returns and trailing spaces are stripped.
Here is an example of a header file contents:

  # This file contain two headers.
.br
  X-header-1: this is a header

  # The following header is folded.
.br
  X-header-2: this is
.br
   another header


To support sending multipart mail messages, the syntax is extended as follows:
.br
- name can be omitted: the equal sign is the first character of the argument,
.br
- if data starts with '(', this signals to start a new multipart: it can be
followed by a content type specification.
.br
- a multipart can be terminated with a '=)' argument.

Example: the following command sends an SMTP mime e-mail consisting in an
inline part in two alternative formats: plain text and HTML. It attaches a
text file:

 curl -F '=(;type=multipart/alternative' \\
.br
         -F '=plain text message' \\
.br
         -F '= <body>HTML message</body>;type=text/html' \\
.br
      -F '=)' -F '=@textfile.txt' ...  smtp://example.com

Data can be encoded for transfer using encoder=. Available encodings are
\fIbinary\fP and \fI8bit\fP that do nothing else than adding the corresponding
Content-Transfer-Encoding header, \fI7bit\fP that only rejects 8-bit characters
with a transfer error, \fIquoted-printable\fP and \fIbase64\fP that encodes
data according to the corresponding schemes, limiting lines length to
76 characters.

Example: send multipart mail with a quoted-printable text message and a
base64 attached file:

 curl -F '=text message;encoder=quoted-printable' \\
.br
      -F '=@localfile;encoder=base64' ... smtp://example.com

See further examples and details in the MANUAL.

This option can be used multiple times.