Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
METAMAIL(1)		    General Commands Manual		   METAMAIL(1)

       metamail	- infrastructure for mailcap-based multimedia mail handling

       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]

       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-

       Note:  Metamail determines the type of a	message	 using	the  "Content-
       type" header, as	defined	in RFC 1049 and	RFC-1341 (MIME).  However, us-
       ing 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"  en-
       coding,	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.

       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

       -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, be-
	       cause 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 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 in-
	       formative  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  de-
	       fault, 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 exe-
	       cuted to	reset the terminal state, before any other I/O	activ-

       -s <subject>
	       This  option specifies the subject of the mail message.	By de-
	       fault, this information is obtained from	the headers.  This in-
	       formation  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,  ei-

       -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 it-
	       self 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.

       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 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

       The default search path is equivalent to


       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-

       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.

	       If set, this variable overrides "/tmp" as the name of  the  di-
	       rectory	in  which metamail and associated programs will	create
	       temporary files on UNIX.

	       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.)

	       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


	       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 ex-
	       amined 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.

	       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.

	       This variable can be used to override the default  path	search
	       for mailcap files.

	       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.

	       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.

	       If MM_DEBUG is set to any value,	metamail will produce slightly
	       more verbose output to tell what	it is doing.

	       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

	       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.

	       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.

	       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.

	       Used to create a	terminal window	under the SunTools window sys-

       WMHOST  Used to create a	terminal window	under the old Andrew WM	window

       When metamail calls an interpreter specified in a mailcap file, it sets
       several	environment  variables which can be used by the	interpreter if

	       This variable is	set to the full	set of RFC822 headers, if any.

	       This variable is	set to the name	 of  the  mailer  that	called
	       metamail, if the	-m option was used.

	       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".

	       This variable is	set to an efficient one-line "caption" of  the
	       message,	typically including its	sender and subject.

	       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, al-
	       lowing -p to work recursively.  This option cannot be used with

	       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.

	       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.

       $HOME/.mailcap:/etc/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap  --
       default path for	mailcap	files.

       audiocompose(1),	audiosend(1),  ezview(1),  getfilename(1),  mailto-he-
       brew(1),	 mailto(1),  metasend(1),  mmencode(1),	 richtext(1),  showau-
       dio(1),	showexternal(1),  shownonascii(1),  showpartial(1),   showpic-
       ture(1),	mailcap(4)

       In  a multipart/alternative body	or body	parts, some headers in the em-
       bedded 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 in-
       conceivable  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 (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-

       Nathaniel S. Borenstein

Bellcore Prototype		   Release 2			   METAMAIL(1)


Want to link to this manual page? Use this URL:

home | help