docs/cmdline-opts/form.d

   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
   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 profile=@portrait.jpg https://example.com/upload.cgi
  35
  36 Example: send a 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 a 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 "web=@index.html;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 '=@textfile.txt' ...  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.