0066d169e8
The entire ASCII version of the manpage word wraps at a fixed column, while example command lines can easily go wider than so. This change now makes manage work on wrapping long example command lines to make them look nicer. And also to avoid triggering the build error caused by too long lines in the output. Quoted lines cannot be wrapped, so managen now errors out if they are "too long". With this addition, the 'maxline' script is removed as it is no longer needed. Closes #14543
146 lines
5.1 KiB
Markdown
146 lines
5.1 KiB
Markdown
---
|
|
c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
SPDX-License-Identifier: curl
|
|
Long: form
|
|
Short: F
|
|
Arg: <name=content>
|
|
Help: Specify multipart MIME data
|
|
Protocols: HTTP SMTP IMAP
|
|
Mutexed: data head upload-file
|
|
Category: http upload post imap smtp
|
|
Added: 5.0
|
|
Multi: append
|
|
See-also:
|
|
- data
|
|
- form-string
|
|
- form-escape
|
|
Example:
|
|
- --form "name=curl" --form "file=@loadthis" $URL
|
|
---
|
|
|
|
# `--form`
|
|
|
|
For the HTTP protocol family, emulate a filled-in form in which a user has
|
|
pressed the submit button. This makes curl POST data using the Content-Type
|
|
multipart/form-data according to RFC 2388.
|
|
|
|
For SMTP and IMAP protocols, this composes a multipart mail message to
|
|
transmit.
|
|
|
|
This enables uploading of binary files etc. To force the 'content' part to be
|
|
a file, prefix the filename with an @ sign. To just get the content part from
|
|
a file, prefix the filename 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.
|
|
|
|
Read content from stdin instead of a file by using a single "-" 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 not subject to buffering and is instead 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** is 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 instruct 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=@\"local,file\";filename=\"name;in;post\"" \
|
|
https://example.com
|
|
|
|
or
|
|
|
|
curl -F 'file=@"local,file";filename="name;in;post"' \
|
|
https://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' \
|
|
https://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.
|
|
X-header-1: this is a header
|
|
|
|
# The following header is folded.
|
|
X-header-2: this is
|
|
another header
|
|
|
|
To support sending multipart mail messages, the syntax is extended as follows:
|
|
|
|
- name can be omitted: the equal sign is the first character of the argument,
|
|
|
|
- if data starts with '(', this signals to start a new multipart: it can be
|
|
followed by a content type specification.
|
|
|
|
- a multipart can be terminated with a '=)' argument.
|
|
|
|
Example: the following command sends an SMTP mime email consisting in an
|
|
inline part in two alternative formats: plain text and HTML. It attaches a
|
|
text file:
|
|
|
|
curl -F '=(;type=multipart/alternative' \
|
|
-F '=plain text message' \
|
|
-F '= <body>HTML message</body>;type=text/html' \
|
|
-F '=)' -F '=@textfile.txt' ... smtp://example.com
|
|
|
|
Data can be encoded for transfer using encoder=. Available encodings are
|
|
*binary* and *8bit* that do nothing else than adding the corresponding
|
|
Content-Transfer-Encoding header, *7bit* that only rejects 8-bit characters
|
|
with a transfer error, *quoted-printable* and *base64* 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' \
|
|
-F '=@localfile;encoder=base64' ... smtp://example.com
|
|
|
|
See further examples and details in the MANUAL.
|