METAMAIL(1)                                           METAMAIL(1)

NAME
       metamail  -  infrastructure  for  mailcap-based multimedia
       mail handling

SYNOPSIS
       metamail[-b] [-B] [-c contenttype ...] [-d] [-e] [-E  con-
       tentencoding]  [-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 mod-
       ified 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  automati-
       cally  by the user's mail reading program, whenever a non-
       text message is to be viewed.  This  manual  page,  there-
       fore,  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  con-
       cerned with the command line syntax of metamail.  The lat-
       ter 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 for-
       mat, 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  new-
       lines  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 "needstermi-
               nal" 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  ques-
               tions  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  envi-
               ronment 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  new-
               lines  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 environ-
               ment variable METAMAIL_PAGER can be used to  spec-
               ify  an alternative command to use.  Note that one
               should use -p rather than  piping  the  output  of
               metamail  through  a  pager,  because  some inter-
               preters called by metamail  might  be  interactive
               rather  than  requiring  pagination.  Metamail can
               tell whether or not to use a pager  from  informa-
               tion  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 meta-
               mail 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  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/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 mes-
               sage.  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 con-
               sulting 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  vari-
               able.)   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 pro-
       grams 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 pro-
       gram to run in order to show the user mail in a given for-
       mat.  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/mail-
       cap:/etc/mailcap:/etc/mail/mailcap:/usr/public/lib/mail-
       cap"

       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 inter-
               preter.  Otherwise,  MM_NOASK  may  be  set  to  a
               comma-separated  list of type names (without white
               space) for which the user does not desire  confir-
               mation.    Thus,   setting   MM_NOASK  to  "magic-
               mail,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 recur-
               sively.)

       KEYHEADS
               The KEYHEADS variable may be set to a  colon-sepa-
               rated  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 pro-
               cesses, 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 read-
               ing  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 pro-
               duce  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 "Execut-
               ing..." 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  com-
               plex 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 charac-
               ter  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  Sun-
               Tools 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_CONTENT-
               TYPE, 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/mail-
       cap:/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),  mail-
       cap(4)

BUGS
       In a multipart/alternative body or body parts, some  head-
       ers  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,  regard-
       less  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 mate-
       rial for any purpose and without fee  is  hereby  granted,
       provided  that the above copyright notice and this permis-
       sion notice appear in all copies, and  that  the  name  of
       Bellcore  not be used in advertising or publicity pertain-
       ing 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 PRO-
       VIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED  WARRANTIES.

AUTHOR
       Nathaniel S. Borenstein

Bellcore Prototype          Release 2                           1