Provided by: metamail_2.7-54_i386 bug

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.

       -E <contentencoding>
               This  option  tells  metamail  to  use  the  specified  content
               transfer 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
               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/bin/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(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
               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),    mimencode(1),    richtext(1),
       showaudio(1),    showexternal(1),    shownonascii(1),   showpartial(1),
       showpicture(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
       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