A mailcap file is a textual configuration file. It contains entries that associate MIME Content-types with various programs to view, compose, or edit that Content-type. An entry may also contain other supporting information about the programs or the Content-type that is necessary to properly handle the data.

Mailcap entries may be single line or multiline. Multiline entries may be made by ending intermediate lines with a backslash () character. Blank lines and lines beginning with a hash (#) character are ignored when parsing mailcap files. Any characters on a line beginning with a hash character are considered to be comments.

Each entry in the file begins with a MIME Content-type (MIME type and subtype), followed by a number of fields. Some fields are name-value pairs, and others are single words. Fields are separated by semicolons (;). Possible fields are described here, but note that specific applications can define their own fields by using the common “X-” syntax as described in Chapter 2, Simple Text Messages.

The second field after the Content-type lists the program to run in order to view data of that type. It is known as the view field and is the only other mandatory field. If an entry for a given Content-type exists, it must have at least a view field defined.

The syntax to call a program is naturally dependent on the underlying operating system; we’ll look at some operating system specifics later in this chapter.

A view field should consist only of a program command line whose syntax is proper for the underlying system. For Unix, this means that the program command line should assume that it has an implicit /bin/sh -c preceding it. For example, suppose that you wanted to use John Bradley’s excellent xv program to view image data in JPEG format. On a Unix system, a minimal mailcap entry might look like this:

# Handle JPEG images with xv
image/jpeg;/usr/X11R6/bin/xv %s

The %s argument (under Unix) passes the data to the viewing program as a temporary file. This syntax is operating system specific but shown here to give a feel for a program entry. The % syntax for Unix is fully discussed in “Implementation Under Unix Operating Systems,” later in this chapter.

There are many optional fields for a mailcap entry. The first of these is the compose field. Unlike the view field, this field’s syntax is as a name-value pair: compose=<program name%gt;. The purpose of this field is to provide a program that can create (or compose) data in the MIME Content-type specified. If a mailcap file includes a compose field, then an application using the file can determine how content of that type may be created on demand.

The composetyped field serves exactly the same purpose as the compose field, but a program specified must be capable of creating not only data of the appropriate type but also the associated MIME headers. This is a subtlety but an important one. This field should be used if the program is expected to return an entire MIME attachment.

The edit field is also a name-value pair syntax. It provides a program command line to use when an application needs to edit data of the specified MIME type. This may be the same program as used for the compose field (and probably will be).

The print field is similar to the edit field; it is a name-value pair that gives a program name to be used to print data of the specified type.

The test field can be used to specify a program to test whether a given entry should be used. The program must have a way to report its success or failure. Under Unix, the program must return either an exit code of zero (0) meaning that the line should be used or a nonzero exit code, otherwise. Other operating systems (that mayor may not implement exit codes for programs) may do this differently.

For example, the test field may be used to determine if the local machine is running a window manager at the moment or if it currently has a sound card configured. That way, programs reading the mailcap file have a way to determine which mailcap entry to use. The xv program may be used to show an image file if the X Window System is running and another entry specify that the zgv program be used if it is not. xv requires X Window, but zgv will display an image to an interactive terminal.

If the test fails, another mailcap entry should be sought for the same Content-type. If no more entries are found, then the mailcap file holds no entries that are currently capable of handling the specified data type.

Some programs, commonly called command-line programs, require an interactive terminal in order to run. An interactive terminal is an interface for running nongraphical programs, such as one might find on Unix systems. The Microsoft Windows family of operating systems provides limited terminals with the command.com and cmd.exe programs. Macinitosh users may never have seen one of these beasties and shouldn’t be concerned if they can’t find one.

MUAs should presume that the test field applies equally to attempts to view, compose, or edit.

The copiousoutput field is a single word of warning. It notes that the program run may produce lots of results and that the MUA might consider buffering it.

The description field is a name-value pair that provides a textual description of the MIME Content-type for an entry. If this field is present, an MUA can parse the description and provide it to a user as further explanation of the data.

If the textualnewlines field is set to a non-zero value, note that the data is assembled from lines. If the data is encoded in base64, all end-of-line markers should be converted to the canonical CRLF form prior to encoding. This field is not normally necessary for Content-types of text/* unless the data is not line oriented. In that case, this field should be set to zero (0) to note that the data is not line oriented.

The x11-bitmap field is a name-value pair that names an image file in .xbm format. This image may be used as an icon for files, attachments, or data of the specified type. The fact that this field assumes a certain format and that the format is of X Windows origin points to some Unix bias. This does not mean that the same concept cannot be used on other systems.

The nametemplate field effects the way temporary files are named for the given Content-type. Temporary files may be created in order to pass the data to a handling program, if that program can’t accept the data as direct input. If a handling program requires the creation of a temporary file and it also expects a given naming convention (e.g., a GIF image ending in “.gif”), this field can be used to name the temporary file appropriately. See the section “Implementation Under Unix Operating Systems,” later in this chapter, for an example under Unix. Table 8-1 lists the mailcap file fields.

If an application wishes to define its own mailcap field, it may do so by beginning its name with “X-”. That naming scheme prevents any conflicts with fields defined in the future. Of course, if you choose to invent such a field, it would help to advertise its existence so others could use it.