metamail(1) DG/UX R4.11MU05 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]
[-R] [-s subject] [-q] [-T] [-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. In the DG/UX system, mailx has been
modified to call metamail for MIME messages.
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.
Note: metamail determines the type of a message using the Content-
type header, as defined in RFC1049 and RFC1521 (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 RFC1521. 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 RFC822 format message on its standard input. The following
options can alter that expectation:
-b The message is not in RFC822 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 Display the message 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
Use the specified ~Content-type rather than the one in
the headers, if any.
-d Do not 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 MMNOASK environment
variable is not set. However, it does not ask about the
Content-type of text, that is, the default value for
MMNOASK is text,text/us-ascii.)
-e Suppress leading newline characters in message bodies.
-E encoding
Specifies how the message is encoded (base64 or quoted-
printable). Normally this information is found in the
mail header and is not supplied as a command-line
argument.
-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 print field (of the
matching mailcap entry) 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 Show output 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 METAMAILPAGER 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.
-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 permissable 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 MMRUNASROOT environment variable.
-R Specifies that the /usr/bin/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.
-T Used by metamail recursively, to turn off the effect of
the MMTRANSPARENT environment variable. It should only
be used when the metamail program restarts itself in a
terminal emulator window.
-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 MMNOTTTY.
-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 know how to 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 MMYANKMODE
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).
filename
This is 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 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.
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/mail/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap
It can be overridden by setting the MAILCAPS environment variable.
Metamail will search all the mailcap files it finds until it locates
the definition for the desired content-type. 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
METAMAILTMPDIR
If set, this variable overrides /tmp as the name of the
directory in which metamail and associated programs will
create temporary files on UNIX.
MMNOASK
If MMNOASK is set to 1, metamail will never ask the
user for confirmation before running an interpreter.
Otherwise, MMNOASK 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, MMNOASK 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 headers 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.
MMNOTTTY
If MMNOTTTY is set to any nonzero value, metamail will
assume that it is not running in a terminal window.
MMNOTTTY implies setting MMNOASK to 1. If -z is
given, MMNOTTTY 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.
METAMAILPAGER
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) 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.
MMDEBUG
If MMDEBUG is set to any value, metamail will produce
slightly more verbose output to tell what it is doing.
MMQUIET
If this variable is set to 1, metamail will produce even
less output than usual. In particular, it will suppress
the Executing... line unless MMDEBUG is set.
Otherwise, this variable can be set to a comma-separated
list of short commands (command names, without args,
used to display MIME objects), and the Executing... line
will be suppressed for those commands only. The default
setting for MMQUIET 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.
MMYANKMODE
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 MMYANKMODE 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.
MMTRANSPARENT
If this variable is set, metamail will reproduce the
entire raw message on stdout, and will open up a new
terminal emulator window in which to do something more
intelligent. This option supports certain mail readers
that depend on the output of the UNIX mail program being
the same as the raw message in the database.
MMCHARSET
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 MMCHARSET 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.
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:
MMHEADERS
This variable is set to the full set of RFC822 headers,
if any.
MMMAILER
This variable is set to the name of the mailer that
called metamail, if the -m option was used.
MMCONTENTTYPE
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 MMCONTENTTYPE, for example,
multipart/mixed; boundary=foobar.
MMSUMMARY
This variable is set to an efficient one-line "caption"
of the message, typically including its sender and
subject.
MMUSEPAGER
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, MMUSEPAGER is set for
spawned processes, allowing -p to work recursively.
This option cannot be used with -B.
TERMINALCMD
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 xterm -e if DISPLAY
is set.
MMRUNASROOT
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/mail/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap
SEE ALSO
mailto(1), metasend(1), mimencode(1), getfilename(1M), richtext(1M),
showexternal(1M), shownonascii(1M), showpartial(1M), showpicture(1M),
mailcap(4), mime(5)
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.
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.
Author is Nathaniel S. Borenstein, Bell Communications Research, Inc.
Licensed material--property of copyright holder(s)