mailcap(4) DG/UX R4.11 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. 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 display-command to execute, and a set of optional
"flag" values.
Syntax for a mailcap entry is as follows:
Content-type; display-command [; compose=compose-cmd]
[; edit=edit-cmd] [; description=string]
[; label=string] [; print=string]
[; composetyped=compose-cmd] [; test=test-cmd]
[; textualnewlines=num] [; notes=string]
[; copiousoutput] [; needsterminal]
For example, a simple mailcap entry would look like this:
text/plain; cat %s
The optional flags can be used to specify additional information
about the mail-handling command. For example:
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 Content-type field (text/plain, in the above example) is simply
any legal Content-type name, as defined by RFC1521. 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 Content-type field may specify a subtype (for
example, text/ISO-8859-1) or a wildcard to match all subtypes (for
example, image/*).
The display-command field is any UNIX command (cat %s in the above
example), and is used to specify the interpreter 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
enclosed in backslashes.
Special escapes that may be used by the display-command include: %s,
%t, %n, and %F
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 character, including itself.)
If no %s appears in the display-command field, then instead of
placing the message body in a temporary file, metamail 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.
Two special codes can appear in the viewing command for objects of
Content-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 created, 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.
Other fields and flags used in mailcap include:
compose=compose-cmd
compose-cmd is a command that is used to specify how to
create a MIME object of the entry's Content-type. See
the mailcap file for examples.
edit=edit-cmd
edit-cmd is a command that is used to specify how to
edit a MIME object of the entry's Content-type. See
EXAMPLESFP below.
description=string
string is used by mailto in a menu entry to allow the
user to create a MIME object of the entry's Content-
type.
label=string
This is synomous to the description field.
print=print-cmd
This is used by metamail when metamail is invoked with
the -h switch; the display-command in the mailcap entry
is bypassed, and print-cmd is invoked instead.
composetyped=compose-cmd
compose-cmd indicates that the object being composed is
already in MIME format; this is primarily used when
using extcompose to create a reference to an external
object.
test=test-cmd
test-cmd is a command that is executed to determine
whether or not the mailcap line actually applies. That
is, if the Content-type field matches the Content-type
on the message, but a test= field is present, then the
test must succeed before the mailcap line is considered
to match the message being viewed. The command may be
any UNIX command, using the same syntax and the same %
escapes as for the viewing command, as described above.
A command is considered to succeed if it exits with a 0
exit status, and to fail otherwise.
textualnewlines=num
This field can be used in the rather obscure case where
the default metamail rules for treating base64-encoded
newlines are unsatisfactory. By default, metamail will
translate CRLF to the local 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 textual Content-types.
notes=string
string is an uninterpreted string that is used to
specify the name of the person who installed this entry
in the mailcap file. string may be any text string.
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 copiousoutput, and pagination
has been requested via the -p command, then the output
of the command being executed is piped through a
pagination program (more by default, but this can be
overridden with the METAMAILPAGER environment
variable).
needsterminal
If this flag is given, the named interpreter needs to
interact with the user on a terminal. In some
environments (for example, 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 MMNOTTTY
environment variable) then metamail will try to run the
command in a new terminal emulation window.
BUILT-IN CONTENT-TYPE SUPPORT
The metamail program has built-in support for a few key Content-
types. In particular, it supports Content-types of text, multipart
and multipart/alternative, and message/rfc822. 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 Content-types that
are totally unrecognized -- for which no mailcap entry or built-in
handler exists. For such unrecognized Content-types, metamail will
write a file with a "clean" copy of the data -- a copy in which all
mail headers have been removed, and in which any 7-bit transport
encoding has been decoded.
EXAMPLES
image/gif; showpicture %s; compose="xwd -frame | xwdtopnm | \
ppmtogif > %s; exit 0"; \
description="An X11 window image dump in GIF format"
message/partial; showpartial %s %{id} %{number} %{total}
message/external-body; showexternal %s %{access-type} \
%{name} %{site} %{directory} %{mode} %{server}; \
needsterminal; composetyped = extcompose %s; \
description="A reference to data stored in an external location"
application/postscript ; lp -dps2 %s ; description="A \
Postscript File"; compose="getfilename Postscript %s"
text/enriched; shownonascii iso-8859-1 -e richtext -e -p %s; \
test=test "`echo %{charset} | tr '[A-Z]' '[a-z]'`" \
= iso-8859-1; copiousoutput
FILES
The default path for mailcap files is:
$HOME/.mailcap:/etc/mail/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap
SEE ALSO
metamail(1), mime(5), terminfo(4)
NOTICES
Author is Nathaniel S. Borenstein, Bell Communications Research, Inc.
Licensed material--property of copyright holder(s)