metamail

METAMAIL(1)                 General Commands Manual                METAMAIL(1)



NAME
       metamail - infrastructure for mailcap-based multimedia mail handling

SYNOPSIS
       metamail[-b] [-B] [-c contenttype ...] [-d] [-e] [-E contentencoding]
       [-f  from-name] [-h] [-m mailer-name] [-p] [-P] [-r] [-s subject] [-q]
       [-w] [-x] [-y] [-z] [file-name]

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 will discuss 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 will never run metamail directly.  Instead, metamail
       will be invoked for the user automatically 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 to 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 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      This option tells metamail that the message is not in RFC 822
               format, but instead is only the body of the message (i.e. there
               are no message headers).  The use of -b requires the use of -c.

       -B      This option tells metamail that the message is to be displayed
               in the background, if it is non-interactive (i.e. it doesn't
               have the "needsterminal" attribute in the mailcap file).  It
               cannot be used with -p or -P.

       -c <contenttype>
               This option 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 "text" -- that is, the default value for
               MM_NOASK is "text,text/us-ascii")

       -e      This option tells metamail to "eat" leading newlines in message
               bodies.  This is particularly useful for MH-format mail.

       -f <address>
               This option 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      This option specifies that metamail is being used for printing
               a message.  In particular, this means that the normal mailcap
               "command" field will not be executed, but instead the command
               specified in the "print" 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>
               This option 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      This option 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      This option is 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      This option tells metamail to be quiet.  By default, metamail
               prints a few key message headers (controllable with the
               KEYHEADS and KEYIGNHEADS environment variables) and some other
               informative information, on stdout before running the
               interpreter, but this behavior is suppressed with -q.

       -r      This option specifies that it is OK 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      This option specifies that the /usr/ucb/reset should be
               executed to reset the terminal state, before any other I/O
               activity.

       -s <subject>
               This option 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      This option tells metamail that instead of consulting a mailcap
               file to decide 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 file name to use from the message
               headers, by asking the user, or by generating a unique
               temporary file name.

       -x      This option tells metamail that it is definitely not running on
               a terminal, no matter what isatty() says.  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      This option 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 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
               VERY strange.  It won't hurt you, but you won't see anything
               very useful, either.

       -z      This option tells metamail to delete its input file when
               finished.  The -z option requires that a file name was given as
               an argument to metamail, i.e. that it is not reading stdin.

       -T      This option is intended to be 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.

       File Name Arguments
               Any argument that does not start with "-" is interpreted as the
               name of a file to read instead of standard input.

UNRECOGNIZED MAIL TYPES
       From time to time, metamail may tell you something like

       **** Unrecognized mail type: 'smell-o-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 "smell-o-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 give you more alternatives -- writing it
       to a temporary file, viewing it as text, or jus skipping it.)  It is up
       to the user to delete such files when he or she is through with them.


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:/usr/local/etc/mailcap:/usr/etc/mailcap:/etc/mailcap:/etc/mail/mailcap:/usr/public/lib/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.

       The format of mailcap files is explained in the manual entry for
       mailcap(4).


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 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.  Thus, setting MM_NOASK to "magicmail,audio" will
               cause the user not to be asked before running interpreters for
               magicmail- or audio-format mail, but the user will still be
               asked for all other types.  (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) 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 a new terminal emulator
               window in which to do something more intelligent.  This option
               supports certain brain-dead mail readers, such as mailtool,
               that actually 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, e.g. "multipart/mixed;
               boundary=foobar".

       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
       $HOME/.mailcap:/etc/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap --
       default path for mailcap files.

SEE ALSO
       audiocompose(1), audiosend(1), ezview(1), getfilename(1), mailto-
       hebrew(1), mailto(1), metasend(1), mmencode(1), richtext(1),
       showaudio(1), showexternal(1), shownonascii(1), showpartial(1),
       showpicture(1), mailcap(4)

BUGS
       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 of
       type "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.

       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.  I have been unable to conceive
       of a situation where this would be a real problem, because it seems
       inconceivable that a single content-type would ever require newlines to
       be treated in two different ways, regardless of the environment.

       The "%n" and "%F" mailcap fields do not work in "test" clauses, because
       metamail does not perform sufficient lookahead to do this right.

COPYRIGHT
       Copyright (c) 1991 Bell Communications Research, Inc. (Bellcore)

       Permission to use, copy, modify, and distribute this material for any
       purpose and without fee is hereby granted, provided that the above
       copyright notice and this permission notice appear in all copies, and
       that the name of Bellcore not be used in advertising or publicity
       pertaining to this material without the specific, prior written
       permission of an authorized representative of Bellcore.  BELLCORE MAKES
       NO REPRESENTATIONS ABOUT THE ACCURACY OR SUITABILITY OF THIS MATERIAL
       FOR ANY PURPOSE.  IT IS PROVIDED "AS IS", WITHOUT ANY EXPRESS OR
       IMPLIED WARRANTIES.

AUTHOR
       Nathaniel S. Borenstein



Bellcore Prototype                 Release 2                       METAMAIL(1)