metamail(1) metamail(1)
NAME
metamail - infrastructure for mailcap-based multimedia mail
handling
SYNOPSIS
metamail [-b] [-B] [-c contenttype . . .] [-d] [-e] [-E encoding]
[-f from-name] [-h] [-m mailer-name] [-p] [-P] [-r]
[-s subject] [-q] [-w] [-x] [-y] [-z] [filename]
DESCRIPTION
The metamail program reads a mailcap file to determine how to
display non-text at the local site. Every mail-reading
interface needs to call metamail whenever non-text mail is
being viewed, unless the mail is of a type that is already
understood by the mail-reading program.
metamail consults the mailcap file(s) to determine what
program to use to show the message to the user.
At a site where all mail reading interfaces have been modified
to call metamail for non-text mail, extending the local email
system to handle a new media type in the mail becomes a simple
matter of adding a line to a mailcap file.
Although this manual page discusses only mail, metamail is
equally useful in adding multimedia support to news and
bulletin board reading programs, assuming those programs
preserve the Content-type header or some other indication of
the Content-type of the messages.
In general, users never run metamail directly. Instead,
metamail is invoked automatically on behalf of the user by the
user's mail reading program, whenever a non-text message is to
be viewed.
This manual page, therefore, is directed not at end users, but
at two categories of readers: those who are adding metamail
support to a particular mail-reading program, and those who
are adding lines to a mailcap file. The former need only be
concerned with the command line syntax of metamail. The
latter may ignore the command line syntax and need only be
concerned with the mailcap file syntax, as described in a
later section.
Copyright 1994 Novell, Inc. Page 1
metamail(1) metamail(1)
Note: metamail determines the type of a message using the
Content-type header, as defined in RFC 1049 and RFC-1341
(MIME). However, using the -b and -c options, metamail can be
made to work with mail that is not in Internet format,
including X.400 messages. Note also that metamail
automatically decodes mail that has been encoded for 7-bit
transport if the mail includes a Content-Transfer-Encoding
header as specified by RFC-1341. If data has been encoded via
the "base64" encoding, it will map CRLF to local newlines for
textual data, but not for other data, unless instructed
otherwise by a textualnewlines field in a mailcap entry.
OPTIONS
When called with no options or arguments, metamail expects to
receive an RFC 822 format message on its standard input. The
following options can alter that expectation:
-b Tells metamail that the message is not in RFC 822
format, but instead is only the body of the
message (that is, there are no message headers).
The use of -b requires the use of -c.
-B Tells metamail that the message is to be displayed
in the background, if it is non-interactive (that
is, it doesn't have the needsterminal attribute in
the mailcap file). It cannot be used with -p or
-P.
-c contenttype
Tells metamail to use the specified ~Content-type
rather than the one in the headers, if any.
-d This option tells metamail not to ask any
questions before running an interpreter to view
the message. (By default, metamail always asks
before running almost any interpreter, if it is
running in an interactive terminal and the
MM_NOASK environment variable is not set.
However, it does not ask about the Content-type of
text, that is, the default value for MM_NOASK is
text,text/plain.)
-e Tells metamail to suppress leading newline
characters in message bodies. This is
particularly useful for MH-format mail.
Copyright 1994 Novell, Inc. Page 2
metamail(1) metamail(1)
-f address
Specifies the name of the sender of the message.
Otherwise, this is determined from the header, if
possible. This information will be placed in the
environment to make it available to any
interpreters called by metamail.
-h Specifies that metamail is being used for printing
a message. In particular, this means that the
normal command field in mailcap will not be
executed but instead the command specified in the
prints field will be executed. (If there is
nothing in the print field, the mailcap entry will
be ignored and the search will continue for a
matching mailcap entry that does have a print
field.) The -h option automatically turns on the
-d option.
-m mailername
Specifies the name of the mail program that called
metamail. This information will be placed in the
environment to make it available to any
interpreters called by metamail.
-p Specifies that, if necessary, output should be
shown to the user one page at a time. By default,
this will cause such output to be piped through
the more command, but the environment variable
METAMAIL_PAGER can be used to specify an
alternative command to use. Note that one should
use -p rather than piping the output of metamail
through a pager, because some interpreters called
by metamail might be interactive rather than
requiring pagination. Metamail can tell whether
or not to use a pager from information in the
mailcap file. This option cannot be used with -B.
-P Just like -p, except that it also causes metamail
to print Press RETURN to go on and await a RETURN
after it has finished with the message. This is
intended for use only when metamail calls itself
recursively in a new terminal window created only
for that purpose. This option cannot be used with
-B.
Copyright 1994 Novell, Inc. Page 3
metamail(1) metamail(1)
-q Tells metamail to be quiet. By default, metamail
prints a few key message headers (controllable
with the KEYHEADS environment) and some other
informative information, on stdout before running
the interpreter, but this behavior is suppressed
with -q.
-r Specifies that it is permissible to run as root.
By default, metamail refuses to run if the real or
effective user id is root. You can get the same
effect using the MM_RUNASROOT environment
variable.
-R Specifies that the /usr/ucb/reset should be
executed to reset the terminal state, before any
other I/O activity.
-s subject
Specifies the subject of the mail message. By
default, this information is obtained from the
headers. This information will be placed in the
environment to make it available to any
interpreters called by metamail.
-w Tells metamail that instead of consulting a
mailcap file to determine how to display the data,
it should simply decode each part and write it to
a file in its raw (possibly binary) format.
Depending on the circumstances in which it is
called, metamail may derive the filename to use
from the message headers, by asking the user, or
by generating a unique temporary file name.
-x Tells metamail that it is definitely not running
on a terminal, no matter what isatty indicates.
This is necessary when metamail is actually
running on a pseudoterminal and isatty(3) returns
TRUE but there's really no terminal on which to
interact with the user. The same effect as -x can
also be obtained with the environment variable
MM_NOTTTY.
-y Tells metamail to try to "yank" a MIME-format
message from the body of the message. It is
useful when a MIME-format has been rejected by a
mail delivery system that does not now how to
Copyright 1994 Novell, Inc. Page 4
metamail(1) metamail(1)
format the rejection in a MIME-compliant manner.
(For the convenience of those who can't control
how metamail is called from their mail reader,
this can also be set with the MM_YANKMODE
variable.) If you use yank mode on messages that
really are in MIME format, or on messages that do
not contain a MIME message in the body, the
effects could be strange.
-z Tells metamail to delete its input file when
finished. The -z option requires that a filename
be given as an argument to metamail, (because it
is not reading stdin.
-T Used by metamail recursively, to turn off the
effect of the MM_TRANSPARENT environment variable.
It should only be used when the metamail program
restarts itself in a terminal emulator window.
filename
Any argument that does not start with minus (-) to
indicate an option is interpreted as the name of a
file to read instead of standard input.
UNRECOGNIZED MAIL TYPES
From time to time, metamail may generate a message:
**** Unrecognized mail type: 'sensor-vision'.
Writing to file /tmp/metamail.1234 ****
What this means is that your are trying to read a message that
contains data that is marked as being in "sensor-vision"
format, but that your site has not yet configured metamail to
properly display that type of data. In the general case, such
configuration is accomplished using the mailcap file
mechanism, as described in the next section.
For unrecognized types, metamail simply removes all header and
encoding information from the data, and writes it out to a
temporary file. (If running interactively, it will offer you
more alternatives - writing it to a temporary file, viewing it
as text, or abandoning the process.) It is up to the user to
delete such files when they are no longer needed.
Copyright 1994 Novell, Inc. Page 5
metamail(1) metamail(1)
THE mailcap FILE(S)
The primary purpose of the metamail program is to allow
diverse mail reading programs to centralize their access to
multimedia information. If all the mail reading programs call
a single program to handle non-text mail, then only that
program needs to know about the diverse types of non-text mail
that might be received.
The metamail program is made more flexible in this role
through the mechanism of one or more mailcap files. The
purpose of the mailcap files is to tell metamail what program
to run in order to show the user mail in a given format. Thus
it becomes possible to add a new media type to all of the mail
reading programs at a site simply by adding a line to a
mailcap file.
metamail uses a search path to find the mailcap file(s) to
consult. Unlike many path searches, if necessary metamail
will read all the mailcap files on its path. That is, it will
keep reading mailcap files until it runs out of them, or until
it finds a line that tells it how to handle the piece of mail
it is looking at. If it finds a matching line, it will
execute the command that is specified in the mailcap file.
The default search path is equivalent to:
$HOME/.mailcap:/etc/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap
It can be overridden by setting the MAILCAPS environment
variable. Note: metamail does not actually interpret
environment variables such as HOME or the ~ syntax in this
path search.
NON-ASCII HEADER FIELDS
metamail has rudimentary built-in support for the emerging
Internet standards for non-ASCII data in mail headers. What
this means is that such data will be recognized, decoded, and
sent to the terminal. This behavior may be more or less
reasonable, depending on the character set in the header data
and the capability of the user's terminal, but it will rarely
be any worse than showing such data in its encoded form.
ENVIRONMENT
METAMAIL_TMPDIR
If set, this variable overrides /tmp as the name
of the directory in which metamail and associated
Copyright 1994 Novell, Inc. Page 6
metamail(1) metamail(1)
programs will create temporary files on UNIX.
MM_NOASK
If MM_NOASK is set to 1, metamail will never ask
the user for confirmation before running an
interpreter. Otherwise, MM_NOASK may be set to a
comma-separated list of type names (without white
space) for which the user does not desire
confirmation. (If the -d command line option is
given, MM_NOASK is set to 1 for spawned processes,
allowing -d to work recursively.)
KEYHEADS
The KEYHEADS variable may be set to a colon-
separated list of header names, which are the only
headers that metamail will print out. By default,
the behavior is as if KEYHEADS were set to:
Date:From:Subject:To:CC:Content-Description
If KEYHEADS is set to the empty string, no header
are printed out. If it is set to an asterisk (*),
all headers are printed out. KEYIGNHEADS The
KEYIGNHEADS variable may be set to a colon-
separated list of header names, which are the
headers that metamail will not print out. This
variable is only examined if KEYHEADS is not set.
If KEYIGNHEADS is set to the empty string, all
headers are printed out. If it is set to an
asterisk (*), no headers will be printed out.
MM_NOTTTY
If MM_NOTTTY is set to any nonzero value, metamail
will assume that it is not running in a terminal
window. MM_NOTTTY implies setting MM_NOASK to 1.
If -z is given, MM_NOTTTY is set for spawned
processes, allowing -z to work recursively.
MAILCAPS
This variable can be used to override the default
path search for mailcap files.
METAMAIL_PAGER
If set, this variable overrides more as the name
of the program to run to paginate output from an
interpreter, when pagination has been requested.
Note that the normal PAGER variable is not used
because many pagers (notably the less pager)
Copyright 1994 Novell, Inc. Page 7
metamail(1) metamail(1)
interfere with the workings of termcap-based mail
viewers.
NOMETAMAIL
This variable is not actually used by metamail,
but is used by most metamail-compatible mail
reading interfaces. If NOMETAMAIL is set to any
value, most mail reading interfaces will never
call the metamail program, effectively inhibiting
all multimedia functionality.
MM_DEBUG
If MM_DEBUG is set to any value, metamail will
produce slightly more verbose output to tell what
it is doing.
MM_QUIET
If this variable is set to 1, metamail will
produce even less output than usual. In
particular, it will suppress the Executing... line
unless MM_DEBUG is set. Otherwise, this variable
can be set to a comma-separated list of short
commands, and the Executing... line will be
suppressed for those commands only. The default
setting for MM_QUIET is cat, which means that the
Executing... line is printed for all commands
executed except cat. This makes text support look
more natural without sacrificing an understanding
of what is going on in more complex circumstances.
MM_YANKMODE
Setting this variable to a non-zero value has the
same effect as the -y switch. Be sure to read the
caveats attached to the description of -y before
you use it. Basically, the only time you would
set MM_YANKMODE is in order to re-enter a mail
reader in which you can't control the way metamail
is called, just to read a single rejected MIME
message that was rejected by a mail agent that
does not understand MIME. In such cases, you
should read that message, exit, and unset this
variable.
MM_TRANSPARENT
If this variable is set, metamail will reproduce
the entire raw message on stdout, and will open up
Copyright 1994 Novell, Inc. Page 8
metamail(1) metamail(1)
a new terminal emulator window in which to do
something more intelligent. This option supports
certain mail readers, such as mailtool, that
depend on the output of the UNIX mail program
being the same as the raw message in the database.
MM_CHARSET
If this variable is set, it will suppress the
printing of character set declarations when mail
headers being printed contain text in this
character set. For example, if you set MM_CHARSET
to ISO-8859-8, it will suppress warnings when
header output is produced in that character set.
DISPLAY
Used to create a terminal window under the X11
window system.
WINDOW_PARENT
Used to create a terminal window under the
SunTools window system.
WMHOST
Used to create a terminal window under the old
Andrew WM window system.
INTERPRETER ENVIRONMENT
When metamail calls an interpreter specified in a mailcap
file, it sets several environment variables which can be used
by the interpreter if desired:
MM_HEADERS
This variable is set to the full set of RFC822
headers, if any.
MM_MAILER
This variable is set to the name of the mailer
that called metamail, if the -m option was used.
MM_CONTENTTYPE
This variable is set to the Content-type, as named
by the Content-type header or passed in via the -c
option. If the Content-type has a subtype and
parameters, these are also included in
MM_CONTENTTYPE, for example, multipart/mixed;
boundary=foobar.
Copyright 1994 Novell, Inc. Page 9
metamail(1) metamail(1)
MM_SUMMARY
This variable is set to an efficient one-line
"caption" of the message, typically including its
sender and subject.
MM_USEPAGER
This variable is set to a non-zero if the use of a
pager has been requested for long output (e.g. the
-p switch was given.) If -p is given, MM_USEPAGER
is set for spawned processes, allowing -p to work
recursively. This option cannot be used with -B.
TERMINAL_CMD
This variable may be set to a string that is used
to start a new terminal window if necessary. The
command to be executed in that window will be
appended to this command. By default, this is set
to something like xterm -e if DISPLAY is set, or
shelltool if WINDOW_PARENT is set. Users of Sun's
OpenWindows may wish to set TERMINAL_CMD to
shelltool if they prefer shelltool over xterm.
MM_RUNASROOT
If set to a non-zero variable, this will allow the
metamail program to be run by root, the same
effect as the -r switch to metamail.
FILES
The default path for mailcap files is:
HOME/.mailcap:/etc/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap
REFERENCES
mailto(1), metasend(1), mimencode(1), getfilename(1M),
richtext(1M), showexternal(1M), shownonascii(1M),
showpartial(1M), showpicture(1M)
NOTICES
In a multipart/alternative body or body parts, some headers in
the embedded part that should be displayed may not be
displayed. This will rarely be a problem. Also, in a
multipart/alternative, anything with a type of multipart or
message is considered to be a recognized part, regardless of
the recognizability of its contents. This might be a problem,
only further experience will tell.
Copyright 1994 Novell, Inc. Page 10
metamail(1) metamail(1)
The textualnewlines field in mailcap entries affects a global
table of exceptions. This means that if there is more than
one mailcap entry for a given Content-type, and they have
conflicting textualnewlines settings, the wrong value may be
used. It is difficult to conceive of a situation where this
would be a real problem, because it seems inconceivable that a
single Content-type would ever require newline characters to
be treated in two different ways, regardless of the
environment.
Author is Nathaniel S. Borenstein, Bell Communications
Research, Inc. See copyright page for further information.
Copyright 1994 Novell, Inc. Page 11