363 lines
17 KiB
HTML
363 lines
17 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
|
|
"http://www.w3.org/TR/REC-html40/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>makemime - MIME utility</title>
|
|
<!-- $Id$ -->
|
|
<!-- SECTION 1 -->
|
|
<meta http-equiv="Content-Type" content="text/html">
|
|
</head>
|
|
|
|
<body text="#000000" bgcolor="#FFFFFF" link="#0000EE" vlink="#551A8B"
|
|
alink="#FF0000">
|
|
<h1>makemime - MIME utility</h1>
|
|
|
|
<h2>SYNOPSIS</h2>
|
|
<code>makemime [options]</code>
|
|
|
|
<p><code>makemime @<i>file</i></code></p>
|
|
|
|
<h2>DESCRIPTION</h2>
|
|
|
|
<p>The <i>makemime</i> tool creates MIME-encoded messages of arbitrary
|
|
complexity. <i>makemime</i> reads one or more individual files, encodes them
|
|
appropriately, adds basic MIME headers, and adds additional headers specified
|
|
via command line options. The result is saved to another file or standard
|
|
output. Complex MIME-encoded messages are created by using options that direct
|
|
<i>makemime</i> to run additional instances of itself, as child processes. The
|
|
child processes create individual parts of a complex MIME message, then the
|
|
parent <i>makemime</i> process combines them together.</p>
|
|
|
|
<p>In simple cases, options for <i>makemime</i> are specified directly on the
|
|
command line. @<i>file</i> specifies that options will be read from a file.
|
|
"@&n" reads options from a pipe on file descriptor #n. "@-" is a shortcut for
|
|
"@&0", which reads options from standard input.</p>
|
|
|
|
<p>When options are read from a file or a pipe, each option must be on a line
|
|
by itself. If an option requires an argument, the argument must follow on the
|
|
next line.</p>
|
|
|
|
<p>For readability, leading whitespace on each line is deleted when options
|
|
are read from a file or a pipe. Empty lines are also ignored, as well as lines
|
|
that begin with the '#' character.</p>
|
|
|
|
<p>Options and their arguments may contain characters that are special
|
|
characters to the shell, such as '(' and ')'. These characters must be
|
|
backslashed when specified on the command line, to avoid their special meaning
|
|
to the shell. These characters MUST NOT be backslashed when options are read
|
|
from a file or a pipe. Similarly, the contents of most headers nearly always
|
|
include spaces. Therefore they must be quoted when specified on the command
|
|
line. Header contents MUST NOT be quoted when options come from a file or a
|
|
pipe.</p>
|
|
|
|
<p><i>makemime</i> reads the contents to be encoded into a MIME message from
|
|
other files. Those files can also be pipes. It is possible to supply both the
|
|
options and a file from the same pipe, by terminating the list of option with
|
|
a line containing the single character "-". The remainder of the pipe will be
|
|
available to be used as an input file (which must be explicitly specified via
|
|
some other option). Of course, only one input file can come from a single
|
|
pipe.</p>
|
|
|
|
<h3>MIME overview</h3>
|
|
|
|
<p>A MIME message consists of one or several MIME sections. MIME headers
|
|
specify how multiple MIME sections are to be interpreted as a whole (whether
|
|
they are attached together, or whether they are alternative representations of
|
|
the same object, or something even more esoteric). This manual page gives a
|
|
very brief, terse, overview of basic MIME concepts. The description is biased
|
|
towards describing the functionality of the <i>makemime</i> utility. The
|
|
complete description of MIME encoding is found in RFCs 2045 through 2048,
|
|
where a formal definition is found.</p>
|
|
|
|
<p>Each file in a MIME message is encoded as a single MIME section. A MIME
|
|
section consists of at least one header line, "Content-Type". The
|
|
"Content-Type" headers gives the type of the data contained in the file. Other
|
|
header lines may also be present. Their relative order does not matter. MIME
|
|
headers are followed by a blank line, then the contents of the file, encoded
|
|
appropriately. All MIME sections generated by <i>makemime</i> will always
|
|
contain another header, "Content-Transfer-Encoding". This header gives the
|
|
encoding method used for the file.</p>
|
|
|
|
<p>The encoding method defaults to "7bit" if this header is absent. 7bit
|
|
encoding is only suitable for plain text messages in the US-ASCII character
|
|
set. The "8bit" encoding method is used by plain text messages in other
|
|
character sets which contain high-bit characters, with their 8th bit set. An
|
|
alternative to 8bit encoding is "quoted-printable". The "base64" encoding
|
|
method is used for files containing binary data.</p>
|
|
|
|
<p>MIME sections that contain text messages have their "Content-Type" header
|
|
set to "text/plain"; or "text/html" for HTML messages. There are also several
|
|
other, rare, content types that can be used. MIME sections that contain other
|
|
kinds of data will use some other, appropriate Content-Type header, such as
|
|
"image/gif", or "audio/x-wav".</p>
|
|
|
|
<p>MIME sections that contain textual content may use the base64 encoding
|
|
method, they are not required to use 7bit, 8bit, or quoted-printable.
|
|
"text/pdf" sections, that contain PDF files, typically consist of binary data,
|
|
and must use base64 encoding. Consequently, MIME sections that typically
|
|
contain binary data, such as image/gif and audio/x-wav, are free to use other
|
|
encoding methods besides base64, as long as all the data can be represented by
|
|
printable characters (but, in practice, that never happens).</p>
|
|
|
|
<p>MIME sections may also contain other, optional, headers such as
|
|
"Content-Disposition", "Content-ID", and "Content-Name". Consult the
|
|
appropriate RFCs for the specific usage of these headers. These headers can be
|
|
added by <i>makemime</i> by using the -a option, as described below. These
|
|
headers play no part in creating the overall structure of a MIME-encoded
|
|
message, and <i>makemime</i> does not care much about these headers. It simply
|
|
includes them, and their content, upon request.</p>
|
|
|
|
<p>Multiple files are encoded into a single message by initially creating a
|
|
MIME section for each file, and then creating a single MIME section that
|
|
contains other MIME sections. A "multipart/mixed" MIME section contains a
|
|
collection of MIME sections that represent different objects, attached
|
|
together. A "multipart/alternative" MIME section contains a collection of MIME
|
|
sections which are alternative representations of the same object, such as an
|
|
HTML and a plain text version of the same message. Other "multipart" MIME
|
|
sections also exist, and their usage is defined by their respective RFCs.</p>
|
|
|
|
<h3>Creating a single MIME section</h3>
|
|
<pre> makemime -c "type" [-e "encoding"] [-o file] \
|
|
[-a "header: value"] [-a "header: value"] file</pre>
|
|
|
|
<p>The -c option reads <i>file</i>, encodes it appropriately, adds a
|
|
"Content-Type" and "Content-Transfer-Encoding" MIME headers, then writes the
|
|
result to standard output. <i>type</i> can be any valid MIME type, except for
|
|
multipart. <i>file</i> can be "-", which specifies standard input. <i>file</i>
|
|
can be "&n" to read the file from file descriptor #n.</p>
|
|
|
|
<p>The optional <i>encoding</i> argument should be specified. It's more
|
|
efficient to do so. <i>encoding</i> must be one of the following: 7bit, 8bit,
|
|
quoted-printable, or base64.</p>
|
|
|
|
<p>If <i>encoding</i> is not specified, <i>makemime</i> reads the <i>file</i>
|
|
twice - once to select the best encoding method, and the second time to encode
|
|
it. If <i>file</i> is a pipe <i>makemime</i> will be forced to create a
|
|
temporary file, which is less efficient if the <i>file</i> is large. However
|
|
letting <i>makemime</i> pick the encoding is probably more convenient if files
|
|
are relatively small.</p>
|
|
|
|
<p>By default the encoded MIME section is written to standard output. The -o
|
|
option writes the MIME section to a <i>file</i>. <i>file</i> can be "&n",
|
|
which writes the MIME section to a pipe on file descriptor #n.</p>
|
|
|
|
<p><i>makemime</i> does not generate any other headers. Particularly, the
|
|
"Mime-Version" header (and others) is required to send a MIME message via
|
|
E-mail. Additional headers are specified by the -a option, which may be used
|
|
multiple times to insert multiple headers. <i>makemime</i> doesn't do anything
|
|
with them except to insert the headers into the generated MIME section.</p>
|
|
|
|
<p>Note that "Mime-Version" is only required for the top level MIME section.
|
|
This header is not required for individual MIME sections that are later
|
|
combined into a multipart MIME collection.</p>
|
|
|
|
<p>Note that the -c option is required to be listed first, the remaining
|
|
options must follow the -c option.</p>
|
|
|
|
<h3>Creating a multipart MIME collection</h3>
|
|
<pre> makemime -m "type" [-e "encoding"] [-o file] \
|
|
[-a "header: value"] [-a "header: value"] file</pre>
|
|
|
|
<p>The -m option is identical in usage to the -c option, except for three
|
|
differences.</p>
|
|
|
|
<p><i>type</i> must be either "multipart/mixed", "multipart/alternative", or
|
|
some other MIME multipart content type. Additionally, "encoding" can only be
|
|
"7bit" or "8bit", and will default to "8bit" if not specified. Finally,
|
|
<i>file</i> must be a MIME-encoded section, NOT a regular file. Usually
|
|
<i>file</i> is also created by <i>makemime</i> (it can also be a pipe, like
|
|
the -c option), but it can be created via any other means.</p>
|
|
|
|
<p>The -m option creates an initial multipart MIME collection, that contains
|
|
only one MIME section, taken from <i>file</i>. The collection is written to
|
|
standard output, or the pipe or the file specified by the -o option. The -j
|
|
option is used to add additional MIME sections to this collection.</p>
|
|
|
|
<h3>Creating a multipart MIME section</h3>
|
|
<pre> makemime -j file1 [-o file] file2</pre>
|
|
|
|
<p>This option appends a MIME section to an existing MIME collection.
|
|
<i>file1</i> contains a MIME collection that's been created by the -m option.
|
|
<i>file2</i> must contain a MIME section that's been created by the -c option.
|
|
The MIME section in <i>file2</i> is appended after the last MIME section in
|
|
<i>file1</i>. The result is written to standard output or the file specified
|
|
by the -o option.</p>
|
|
|
|
<p><i>file1</i> and/or <i>file2</i> can be "&n", which reads the corresponding
|
|
file from a pipe on the indicated file descriptor. The -o option, as always,
|
|
can also specify a file descriptor.</p>
|
|
|
|
<p><i>file1</i> and <i>file2</i> should ideally be created by <i>makemime</i>
|
|
as well. It's also possible to use files created by other software, but with
|
|
some degree of care. <i>makemime</i> is not intended to be a MIME parser, but
|
|
a MIME generator. However some amount of MIME parsing is necessary to append a
|
|
MIME section to an existing MIME collection. <i>makemime</i>'s parsing does a
|
|
sufficient job to append a new section to a MIME collection, as long as the
|
|
MIME headers in the MIME collections are straightforward. Very convoluted MIME
|
|
headers may confuse <i>makemime</i>, and it may not be able to handle
|
|
them.</p>
|
|
|
|
<h3>Recursive MIME collections</h3>
|
|
|
|
<p>MIME collection may contain other MIME collections as well as MIME
|
|
sections. The -m and the -j option may use a multipart MIME collection in
|
|
place of a MIME section automatically, simply because a multipart MIME
|
|
collection is just a special type of a MIME section. The following example
|
|
encodes a text message that can be alternatively represented as HTML or plain
|
|
text, with some additional attachments:</p>
|
|
|
|
<p>1. Create a MIME collection containing a text/plain and a text/html MIME
|
|
section.</p>
|
|
|
|
<p>2. Create a MIME collection consisting of the MIME section generated in
|
|
step one, plus additional MIME sections containing other attachments.</p>
|
|
|
|
<p>For example:</p>
|
|
<pre> # Take two files containing the text and the html version of a message, and
|
|
# add MIME headers to them.
|
|
|
|
makemime -c "text/plain; charset=iso-8859-1" -o tmp1.txt msg.txt
|
|
makemime -c "text/html; charset=iso-8859-1" -o tmp1.html msg.html
|
|
|
|
# Combine the result into a multipart/alternative collection
|
|
|
|
makemime -m "multipart/alternative" -a "Content-Disposition: inline" \
|
|
-o tmp.ma1 tmp1.txt
|
|
makemime -j tmp.ma1 -o tmp.ma2 tmp1.html
|
|
|
|
# Add MIME headers to an image attachment.
|
|
|
|
makemime -c "image/gif" -a "Content-Disposition: attachment" \
|
|
-o tmp2.gif attachment.gif
|
|
|
|
# Create the final multipart/mixed collection
|
|
|
|
makemime -m "multipart/mixed" -a "Mime-Version: 1.0" \
|
|
-o tmp.mm1 tmp.ma2
|
|
makemime -j tmp.mm1 -o output.msg tmp2.gif</pre>
|
|
|
|
<p><i>output.msg</i> now contains the complete MIME collection. Just add the
|
|
subject, from, and to headers (can also be done by additional -a options, of
|
|
course), and send it on its way.</p>
|
|
|
|
<h3>Building complex MIME encodings</h3>
|
|
|
|
<p>There are several different ways to build complete MIME encodings from
|
|
multiple MIME sections. One way is to use temporary files to create MIME
|
|
sections, then combine them together into a single MIME collection. A slightly
|
|
more complicated approach involves setting up pipes between multiple makemime
|
|
processes, in order to avoid using temporary files.</p>
|
|
|
|
<p>This can be done manually, by hand. It is also possible to have
|
|
<i>makemime</i> do this automatically. <i>makemime</i> will set up these pipes
|
|
and run multiple instances of itself to create a single MIME collection, with
|
|
multiple attachments of arbitrary complexity.</p>
|
|
|
|
<p>Any file that's read by the -c, -m, and -j options (-o specifies a file to
|
|
create, and doesn't count) may be replaced by a single argument containing a
|
|
left parenthesis, additional options, then a single argument containing a
|
|
right parenthesis. A single invocation of <i>makemime</i> can only use one -c,
|
|
-m, or -j option. However, another -c, -m, or -j option may be specified
|
|
inside the left and the right parenthesis, and its output is used in place of
|
|
the file it replaced. In the previous example the third and the fourth
|
|
invocation of <i>makemime</i> can be replaced with the following command:</p>
|
|
<pre> makemime -j \( \
|
|
-m "multipart/alternative" \
|
|
-a "Content-Disposition: inline" tmp1.txt \
|
|
\) -o tmp.ma2 \
|
|
tmp1.html</pre>
|
|
|
|
<p>Note that the parenthesis must be backslashed, to avoid their special
|
|
meaning to the shell. An equivalent argument file would have the following
|
|
contents:</p>
|
|
<pre> -j
|
|
(
|
|
-m
|
|
multipart/alternative
|
|
-a
|
|
Content-Disposition: inline
|
|
tmp1.txt
|
|
)
|
|
-o
|
|
tmp.ma2
|
|
tmp1.html</pre>
|
|
|
|
<p>These constructs can be arbitrarily nested, and are limited by the amount
|
|
of available memory and resources. The entire sequence in the previous
|
|
section is equivalent to the following command:</p>
|
|
<pre> makemime -j \
|
|
\( \
|
|
-m "multipart/mixed" \
|
|
-a "Mime-Version: 1.0" \
|
|
\( \
|
|
-j \
|
|
\( \
|
|
-m "multipart/alternative" \
|
|
-a "Content-Disposition: inline" \
|
|
\( \
|
|
-c "text/plain; charset=iso-8859-1" \
|
|
msg.txt \
|
|
\) \
|
|
\) \
|
|
\( \
|
|
-c "text/html; charset=iso-8859-1" \
|
|
msg.html \
|
|
\) \
|
|
\) \
|
|
\) \
|
|
-o output.msg \
|
|
\( \
|
|
-c "image/gif" \
|
|
-a "Content-Disposition: attachment" \
|
|
attachment.gif \
|
|
\)</pre>
|
|
|
|
<p>An equivalent argument file would be:</p>
|
|
<pre> -j
|
|
(
|
|
-m
|
|
multipart/mixed
|
|
-a
|
|
Mime-Version: 1.0
|
|
(
|
|
-j
|
|
(
|
|
-m
|
|
multipart/alternative
|
|
-a
|
|
Content-Disposition: inline
|
|
(
|
|
-c
|
|
text/plain; charset=iso-8859-1
|
|
msg.txt
|
|
)
|
|
)
|
|
(
|
|
-c
|
|
text/html; charset=iso-8859-1
|
|
msg.html
|
|
)
|
|
)
|
|
)
|
|
-o
|
|
output.msg
|
|
(
|
|
-c
|
|
image/gif
|
|
-a
|
|
Content-Disposition: attachment
|
|
attachment.gif
|
|
)</pre>
|
|
|
|
<h2>SEE ALSO</h2>
|
|
<a href="maildrop.html">maildrop(1)</a>, <a
|
|
href="maildropfilter.html">maildropfilter(1)</a>, <a
|
|
href="reformail.html">reformail(1)</a>, <a
|
|
href="reformime.html">reformime(1)</a>, egrep(1), grep(1), <a
|
|
href="courier.html">courier(8)</a>, sendmail(8), <a
|
|
href="http://www.rfc-editor.org/rfc/rfc2045.txt">RFC 2045</a>, <a
|
|
href="http://www.rfc-editor.org/rfc/rfc2046.txt">RFC 2046</a>, <a
|
|
href="http://www.rfc-editor.org/rfc/rfc2047.txt">RFC 2047</a>, <a
|
|
href="http://www.rfc-editor.org/rfc/rfc2048.txt">RFC 2048</a>.</body>
|
|
</html>
|