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

FreeBSD Manual Pages

  
 
  

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

NAME
       metamail	- infrastructure for mailcap-based multimedia mail handling

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

DESCRIPTION
       The metamail program reads a "mailcap" file to determine	how to display
       non-text	at the local site.  Every mail-reading interface needs to call
       metamail	 whenever non-text mail	is being viewed, unless	the mail is of
       a type that is already understood by the	mail-reading  program.	 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, 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.

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.

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

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

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

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/mail-
       cap:/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(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  di-
	       rectory	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 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.

       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,  al-
	       lowing -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-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)

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

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=metamail&sektion=1&manpath=FreeBSD+14.3-RELEASE+and+Ports>

home | help