makemime(1)
NAME
makemime - Create MIME-formatted messages
SYNOPSIS
makemime [options...] makemime [@filename]
DESCRIPTION
makemime creates MIME-formatted messages of arbitrary complexity.
makemime reads one or more individual files, MIME-encodes them, adds
basic MIME headers, and adds any additional headers specified bye
command line options. The result is saved to another file or standard
output. Complex MIME-formatted messages are created by piping together
multiple instances of makemime. Advanced options direct makemime to
fork() itself, and handle the details of setting up all the pipelines.
In most cases, options for makemime come directly from the command
line. @filename reads the options from a file. "@&n" reads options from
a pipe on file descriptor #n. "@-" is a shortcut for "@&0", which reads
options from standard input.
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.
For readability, leading whitespace 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.
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.
makemime reads the content to be formatted as a MIME message from some
other file. The files can also be a pipe. It is possible to supply both
the options and a file from the same pipe, by terminating the options
list 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 by one of the options). Of course, only one input
file can come from a single pipe.
MIME overview
A MIME-formatted message contains one or several MIME sections. MIME
headers specify how multiple MIME sections are to be interpreted as a
whole (whether they are attached together; whether they are alternative
representations of the same content; 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 makemime utility. See RFC 2045[1], RFC 2046[2],
RFC 2047[3], RFC 2048[4], and RFC 2049[4] for a formal definition of
MIME-formatted messages.
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:" header gives the type of the data ontained 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
makemime will always contain another header,
"Content-Transfer-Encoding:". This header gives the encoding method
used for the file; it is an optional header, but makemime always
creates it.
The MIME 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 that use octets with the high bit set.
An alternative to 8bit encoding is "quoted-printable". The "base64"
encoding method is used for files containing binary data (anything
other than plain text).
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".
MIME sections that contain textual content may also use the base64
encoding method, they are not required to use 7bit, 8bit, or
quoted-printable. "text/pdf" sections, that contain PDF files,
typically contain binary data and must use the base64 encoding.
Consequently, MIME sections that typically contain binary data, such as
image/gif and audio/x-wav, are free to use encodings other than base64,
as long as all the data can be represented by printable characters
(but, in practice, that never happens).
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 makemime by using the -a option, as described below.
These headers play no part in creating the overall structure of a
MIME-encoded message, and makemime does not care much about these
headers. It simply includes them, and their content, upon request.
Multiple files are formatted as a single message MIME message in two
steps: first, by 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.
Creating a single MIME section
makemime {-c "type"} [-e "encoding"] [-o outputfile] [-C "charset"]
[-N "name"] [-a "header: value"...] {filename}
The -c option reads filename, encodes it appropriately, adds the
"Content-Type: type" and "Content-Transfer-Encoding:" MIME headers,
then writes the result to standard output. type can be any valid MIME
type, except for multipart. Setting filename to "-" reads from standard
input. Setting filename to "&n" reads from file descriptor #n.
The -C option sets the MIME charset attribute for text/plain content.
The -N option sets the name attribute for Content-Type:.
encoding argument should be specified. It's more efficient to do so.
encoding must be one of the following: 7bit, 8bit, quoted-printable, or
base64.
If encoding is not specified, makemime reads the filename twice - once
to figure out the best encoding method, and the second time to encode
filename. If filename is a pipe makemime creates a temporary file,
which is not very efficient if filename is large. However letting
makemime pick the encoding method is more convenient if filename is
relatively small.
Another possibility is to omit encoding and set type to auto. This
combination sets "Content-Type:" to either text/plain, or
application/octet-stream, based on the selected encoding.
By default the encoded MIME section is written to standard output. The
-o option writes the MIME section to outputfile. outputfile may be
"&n", which writes the MIME section to a pipe on file descriptor #n.
makemime does not generate any other headers. Particularly, the
"Mime-Version:" header is required for MIME-formatted E-mail messages.
Additional headers are specified by the -a option, which may be used
multiple times to insert multiple headers. makemime doesn't do
anything with them except to insert the headers into the generated MIME
section.
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.
Note
The -c option must occur listed first, the remaining options must
follow the -c option.
Creating a multipart MIME collection
makemime {-m "multipart/type"} [-e "encoding"] [-o outputfile]
[-a "header: value"...] {filename}
The -m option is identical to the -c option, except for three
differences.
type 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,
filename must be a MIME-formatted section, NOT a regular file. Usually
filename is created by a previous invocation of makemime (it can also
be a pipe, like the -c option), but it can be created via any other
means.
The -m option creates an initial multipart MIME collection, that
contains only one MIME section, taken from filename. The collection is
written to standard output, or the pipe or to outputfile.
Creating a multipart MIME section
makemime {-j file1"} [-o outputfile] {file2}
This option adds a MIME section to an existing MIME collection. file1
must be a MIME collection that was previously created by the -m option.
file2 must be a MIME section that was previously created by the -c
option. The -j options adds the MIME section in file2 to the MIME
collection in file1. The result is written to standard output or to
outputfile.
file1 and/or file2 may be "@&n" which reads from file descriptor #n.
The outputfile may also specify a file descriptor.
file1 and file2 should ideally be created by makemime as well. It's
also possible to use MIME-formatted files created by other software,
but with some degree of care. makemime 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.
makemime's parsing is sufficient for appending 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 makemime, and
it may not be able to handle them.
Recursive MIME collections
MIME collection may contain other MIME collections as well as MIME
sections. The -m and the -j options may use a multipart MIME collection
in place of a MIME section automatically 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:
1. Create a MIME collection that has a text/plain and a text/html MIME
section.
2. Create a MIME collection consisting of the MIME section generated in
step one, plus additional MIME sections containing other attachments.
For example:
# 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
output.msg 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.
Building complex MIME encodings
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.
This can be done manually, by hand. It is also possible to have
makemime do this automatically. makemime will set up these pipes and
run multiple instances of itself to create a single MIME collection,
with multiple attachments of complexity limited only by your system's
limit on the maximum number of open files and pipes.
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
makemime 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 makemime
can be replaced with the following command:
makemime -j \( \
-m "multipart/alternative" \
-a "Content-Disposition: inline" tmp1.txt \
\) -o tmp.ma2 \
tmp1.html
Note that the parenthesis must be backslashed, to avoid their special
meaning to the shell. An equivalent argument file would have the
following contents:
-j
(
-m
multipart/alternative
-a
Content-Disposition: inline
tmp1.txt
)
-o
tmp.ma2
tmp1.html
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:
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 \
\)
An equivalent argument file would be:
-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
)
SEE ALSO
maildrop(1)[5], maildropfilter(5)[6], reformail(1)[7], reformime(1)[8], egrep(1), grep(1), courier(8)[9], sendmail(8), RFC 2045[1], RFC 2046[2], RFC 2047[3], RFC 2048[4], RFC 2049[4].
AUTHOR
Sam Varshavchik
Author
NOTES
1. RFC 2045
http://www.rfc-editor.org/rfc/rfc2045.txt
2. RFC 2046
http://www.rfc-editor.org/rfc/rfc2046.txt
3. RFC 2047
http://www.rfc-editor.org/rfc/rfc2047.txt
4. RFC 2048
http://www.rfc-editor.org/rfc/rfc2048.txt
5. maildrop(1)
[set $man.base.url.for.relative.links]/maildrop.html
6. maildropfilter(5)
[set $man.base.url.for.relative.links]/maildropfilter.html
7. reformail(1)
[set $man.base.url.for.relative.links]/reformail.html
8. reformime(1)
[set $man.base.url.for.relative.links]/reformime.html
9. courier(8)
[set $man.base.url.for.relative.links]/courier.html
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
