Back to main site | Back to man page index

MAILCAP(4)                                     Kernel Interfaces Manual                                    MAILCAP(4)



NAME
       mailcap - metamail capabilities file

DESCRIPTION
       The mailcap file is read by the metamail program to determine how to display non-text at the local site.

       The  syntax  of a mailcap file is quite simple, at least compared to termcap files.  Any line that starts with
       "#" is a comment.  Blank lines are ignored.  Otherwise, each line defines a single mailcap entry for a  single
       content type.  Long lines may be continued by ending them with a backslash character, \.

       Each individual mailcap entry consists of a content-type specification, a command to execute, and (possibly) a
       set of optional "flag" values.  For example, a very simple mailcap entry (which is actually a built-in default
       behavior for metamail) would look like this:

       text/plain; cat %s

       The  optional  flags can be used to specify additional information about the mail-handling command.  For exam‐
       ple:

       text/plain; cat %s; copiousoutput

       can be used to indicate that the output of the 'cat' command may be voluminous, requiring either  a  scrolling
       window, a pager, or some other appropriate coping mechanism.

       The  "type"  field (text/plain, in the above example) is simply any legal content type name, as defined by RFC
       822.  In practice, this is almost any string.  It is the string that will be  matched  against  the  "Content-
       type"  header (or the value passed in with -c) to decide if this is the mailcap entry that matches the current
       message.  Additionally, the type field may specify a subtype (e.g. "text/ISO-8859-1") or a wildcard  to  match
       all subtypes (e.g. "image/*").

       The  "command"  field  is  any UNIX command ("cat %s" in the above example), and is used to specify the inter‐
       preter for the given type of message.  It will be passed to the shell via the system(3) facility.   Semicolons
       and  backslashes  within the command must be quoted with backslashes.  If the command contains "%s", those two
       characters will be replaced by the name of a file that contains the body of the message. If it contains  "%t',
       those  two characters will be replaced by the content-type field, including the subtype, if any.  (That is, if
       the content-type was "image/pbm; opt1=something-else", then "%t" would be replaced by "image/pbm".)    If  the
       command field contains  "%{" followed by a parameter name and a closing "}", then all those characters will be
       replaced by the value of the named parameter, if any, from the Content-type header.   Thus,  in  the  previous
       example,  "%{opt1}"  will  be  replaced by "something-else".  Finally, if the command contains "\%", those two
       characters will be replaced by a single % character.  (In fact, the backslash can be used to quote any charac‐
       ter, including itself.)

       If  no  "%s" appears in the command field, then instead of placing the message body in a temporary file, meta‐
       mail will pass the body to the command on the standard input.  This is helpful in saving /tmp file space,  but
       can be problematic for window-oriented applications under some window systems such as MGR.

       Two  special  codes  can appear in the viewing command for objects of type multipart (any subtype).  These are
       "%n" and "%F".  %n will be replaced by the number of parts within the multipart object.  %F will  be  replaced
       by  a series of arguments, two for each part, giving first the content-type and then the name of the temporary
       file where the decoded part has been stored.  In addition, for each file created by %F, a second file is  cre‐
       ated, with the same name followed by "H", which contains the header information for that body part.  This will
       not be needed by most multipart handlers, but it is there if you ever need it.

       The "notes=xxx" field is an uninterpreted string that is used to specify the name of the person who  installed
       this entry in the mailcap file.  (The "xxx" may be replaced by any text string.)

       newline  character  in  decoded  base64 output if the content-type is "text" (any subtype), but will not do so
       otherwise.  A mailcap entry with a field of "textualnewlines=1" will force such translation for the  specified
       content-type,  while "textualnewlines=0" will guarantee that the translation does not take place even for tex‐
       tual content-types.

       The "compose" field may be used to specify a program that can be used to compose a new body or  body  part  in
       the given format.  Its intended use is to support mail composing agents that support the composition of multi‐
       ple types of mail using external composing agents. As with the view-command, the compose command will be  exe‐
       cuted after replacing certain escape sequences starting with "%".  In particular, %s should be replaced by the
       name of a file to which the composed data is to be written by the specified composing program,  thus  allowing
       the  calling  program (e.g. metamail) to tell the called program where to store the composed data.  If %s does
       not appear, then the composed data will be assumed to be written by the composing programs to standard output.
       The result of the composing program may be data that is NOT yet suitable for mail transport -- that is, a Con‐
       tent-Transfer-Encoding may still need to be applied to the data.

       The "composetyped" field is similar to the "compose" field, but is to be used when the composing program needs
       to  specify the Content-type header field to be applied to the composed data.  The "compose" field is simpler,
       and is preferred for use with existing (non-mail-oriented) programs for composing data in a given format.  The
       "composetyped" field is necessary when the Content-type information must include auxiliary parameters, and the
       composition program must then know enough about mail formats to produce output that  includes  the  mail  type
       information,  and to apply any necessary Content-Transfer-Encoding.   Conceptually, "compose" specifies a pro‐
       gram that simply outputs the specified type of data in its raw form, while "composetyped" specifies a  program
       that outputs the data as a MIME object, with all necessary Content-* headers already in place.


       needsterminal
               If  this  flag is given, the named interpreter needs to interact with the user on a terminal.  In some
               environments (e.g. a window-oriented mail reader under X11) this will require the creation  of  a  new
               terminal  emulation  window,  while  in most environments it will not.  If the mailcap entry specifies
               "needsterminal" and metamail is not running on a terminal (as determined by isatty(3), the -x  option,
               and  the  MM_NOTTTY  environment variable) then metamail will try to run the command in a new terminal
               emulation window.  Currently, metamail knows how to create new windows under the X11, SunTools, and WM
               window systems.

       copiousoutput
               This  flag  should  be given whenever the interpreter is capable of producing more than a few lines of
               output on stdout, and does no interaction with the user.  If the mailcap entry  specifies  copiousout‐
               put, and pagination has been requested via the "-p" command, then the output of the command being exe‐
               cuted will be piped through a pagination program ("more" by default, but this can be  overridden  with
               the METAMAIL_PAGER environment variable).

BUILT-IN CONTENT-TYPE SUPPORT
       The  metamail  program  has built-in support for a few key content-types.  In particular, it supports the text
       type, the multipart and multipart/alternative type, and the message/rfc822 types.  This support is  incomplete
       for  many  subtypes  -- for example, it only supports US-ASCII text in general.  This kind of built-in support
       can be OVERRIDDEN by an entry in any mailcap file on the user's search path.  Metamail  also  has  rudimentary
       built-in  support  for types that are totally unrecognized -- i.e. for which no mailcap entry or built-in han‐
       dler exists.  For such unrecognized types, metamail will write a file with a "clean" copy of the data --  i.e.
       a  copy  in  which  all  mail  headers  have  been removed, and in which any 7-bit transport encoding has been
       decoded.

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


AUTHOR
       Nathaniel S. Borenstein



Bellcore Prototype                                    Release 2                                            MAILCAP(4)