Return to form.d CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / cmdline-opts

Annotation of embedaddon/curl/docs/cmdline-opts/form.d, revision 1.1.1.1

1.1       misho       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 profile=@portrait.jpg 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 "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.