metamail(1)



METAMAIL(1)                                                        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.   Meta-
       mail  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 meta-
       mail.  The latter may ignore the command line syntax, and need only  be
       concerned  with  the  mailcap file syntax, as described in a later sec-
       tion.

       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 run-
               ning 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  con-
               tent-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.

       -E <contentencoding>
               This  option tells metamail to use the specified content trans-
               fer encoding rather than the one in the headers, if any.

       -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  interac-
               tive  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 meta-
               mail 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 KEY-
               HEADS and KEYIGNHEADS environment  variables)  and  some  other
               informative  information,  on  stdout before running the inter-
               preter, 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/bin/reset should be exe-
               cuted to reset the terminal state, before any other I/O  activ-
               ity.

       -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 avail-
               able 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 head-
               ers,  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 mes-
               sage 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 fin-
               ished.  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  mail-
       cap(5).

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 con-
               firmation.  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 head-
               ers 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 pro-
               gram to run to paginate output from an interpreter, when  pagi-
               nation  has been requested.  Note that the normal "PAGER" vari-
               able 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  NOMETA-
               MAIL  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 "Exe-
               cuting..." 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 sup-
               pressed 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  sac-
               rificing  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 char-
               acter  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 sys-
               tem.

       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  Con-
               tent-type  header  or passed in via the -c option.  If the con-
               tent-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  OpenWin-
               dows 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), mimencode(1),  richtext(1),  showau-
       dio(1),   showexternal(1),  shownonascii(1),  showpartial(1),  showpic-
       ture(1), mailcap(5)

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 per-
       taining to this material without the specific, prior written permission
       of  an authorized representative of Bellcore.  BELLCORE MAKES NO REPRE-
       SENTATIONS ABOUT THE ACCURACY OR SUITABILITY OF THIS MATERIAL  FOR  ANY
       PURPOSE.   IT  IS PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WAR-
       RANTIES.

AUTHOR
       Nathaniel S. Borenstein

Bellcore Prototype                 Release 2                       METAMAIL(1)

Man(1) output converted with man2html
list of all man pages