# MIME Types

This chapter describes how applications detect MIME types, how to register MIME types, and how to add applications to the GNOME Desktop.

The purpose of this chapter is to make it easy for an administrator to understand how to configure different parts of the MIME database and give an general overview of the MIME system. Therefore we will not attempt to go into details where it is not necessary. For the gory details, it is recommended that you refer to the XDG shared mime info specification.

## Introduction to MIME Types

A Multipurpose Internet Mail Extension [MIME] type identifies the format of a file. Applications such as Internet browsers and email applications use the MIME type of a file to decide which actions to perform on it. For example, an email application can use the MIME type to detect the format of an attachment and choose an appropriate viewer for the file, such as opening a text document with gedit.

As another example, the Nautilus file manager needs to know the MIME type of a file to perform the following tasks:

- Open the file in an appropriate application.

- Display a string that describes the type of file.

- Display an appropriate icon to represent the file.

- Display a list of other applications that can open the file.

MIME types were originally proposed as a standard for identifying the message body of an e-mail message. Now, many systems use MIME types to identify the format of arbitrary files on the file system. MIME types are composed of a top-level media type followed by a subtype identifier, separated by a forward slash character, `/`. One example of a MIME type is `image/jpeg`. The media type in this example is `image` and the subtype identifier is `jpeg`. The top-level media type is meant to be a general categorization about the content of the file, while the subtype identifer is meant to specifically identify the format of the file.

There are eight media types currently blessed by the IANA [Internet Assigned Naming Authority]. These eight media types are

- application
- audio
- image
- message
- model
- multipart
- text
- video

. Many subtypes exist for each media type; for more information, see MIME Media Types at the IANA web site.

Implementation of MIME types in GNOME follows the XDG shared mime info specification. This specification provides the following advantages:

- Standard locations for all MIME related files.

- A standard way for applications to register information about a new MIME type.

- A standard way to retrieve the MIME type for a file.

- A standard way to retrieve information about a MIME type.

The rest of the chapter describes the files and directories that make up the MIME database, details about source XML files, how to create or modify MIME types, how to register applications as handlers for certain MIME types and finally, how to add an application to the GNOME desktop.

## The MIME Database

The MIME database is a collection of files that make up:

- The set of known MIME types

- The method for determing the MIME type of a file

- Meta information regarding a MIME type, such as a human readable description to use when displaying files of this type.

### Location

As an administrator, the most important and basic step to understanding the MIME system is learning the locations where these files are stored. Since the XDG shared mime info specification was drafted by the X Desktop Group, it also makes use of the XDG base directory specification. It is highly recommended that you familiarize yourself with this specification, as it is also important for other system administration tasks such as editing menus. A brief summary of the directory locations as pertaining to the MIME specification is given below.

The MIME database is created from the set of files located in the `$XDG_DATA_HOME/mime` and `$XDG_DATA_DIRS/mime` directories. If these environment variables are unset, then they default to the values `~/.local/share` and `/usr/local/share:/usr/share` respectively. As can be seen from the default value for `$XDG_DATA_DIRS` , each environment variable is actually a colon separated list of directories. The user's database at `$XDG_DATA_HOME/mime` has precedence over the system database at `$XDG_DATA_DIRS/mime` when conflicting definitions are encountered. Similar to the XDG shared mime specification, we will refer to this set of directories as `<MIME>` in the rest of this document.

For example, assuming default paths for the environment variables, Load `<MIME>/text/plain.xml` means to load the following files:

- `~/.local/share/mime/text/plain.xml`

- `/usr/local/share/mime/text/plain.xml`

- `/usr/share/mime/text/plain.xml`

### Contents

The following is a list of directories and files that are found inside the MIME database along with brief descriptions:

`<MIME>/packages/`

- This directory contains any number of XML files, each of which describe a collection of MIME types. By default, the `freedesktop.org.xml` file is installed in the `/usr/share/mime/packages` directory. This file contains all the default MIME types that are widely used and recognized.

  Applications which provide information about new MIME types are to install a single new XML file here. Depending on the prefix where the application is installed, it will create the file in the `/mime/package` subdirectory of one of the directories in `$XDG_DATA_HOME:$XDG_DATA_DIRS`. For example, an application installed to `/usr/bin` should install a new source XML file to the `/usr/share/mime/packages` directory. For more information about the XML files in the `packages` directory, please see mimetypes-source-xml.

`<MIME>/`MEDIA`/`SUBTYPE`.xml`

- These directories and files are automatically generated from the collection of source XML files in the `<MIME>/packages/` subdirectory by the update-mime-database application. For example, for each `mime-type` element in the `/usr/share/mime/packages/freedesktop.org.xml` file, a directory is created at `/usr/share/mime/` with the media type of the MIME type. An XML file is created in that directory with the subtype identifier of that MIME type as well. The contents of the created XML file include comments (and translations for them), subclasses designations and aliases.

  #### Example: `/usr/share/mime/text/plain.xml` file

      <?xml version='1.0' encoding='utf-8'?>
      <mime-type xmlns="http://www.freedesktop.org/standards/shared-mime-info" type="text/plain">
      <!--Created automatically by update-mime-database. DO NOT EDIT!-->
        <comment>plain text document</comment>
        <!-- possibly more translations -->
        <comment xml:lang="es">documento de texto sencillo</comment>
        <comment xml:lang="eu">testu soileko dokumentua</comment>
        <comment xml:lang="fi">perustekstiasiakirja</comment>
        <comment xml:lang="fr">document plein texte</comment>
        <!-- possibly more translations -->
      </mime-type>

  This file is generated by the update-mime-database application, using the default source XML file `freedesktop.org.xml`.

`<MIME>/globs`

- Contains one line with a MIME type and a glob pattern, separated by a colon. Files which match the glob pattern are resolved to the MIME type specified before the colon. There are special rules about how filenames are matched by the glob pattern; for more details see the XDG shared mime specification.

  This file is also generated by the update-mime-database application, using the default source XML file `freedesktop.org.xml`.

`<MIME>/magic`

- A binary file which contains information on how to resolve MIME types by sniffing the content of the file. This is generally a set of one or more rules such as check for the string `%PDF-` at byte offset 0 in the file; if found, assign it the MIME type `application/pdf`.

  This file is also generated by the update-mime-database application.

`<MIME>/XMLnamespaces`

- Contains a mapping of XML namespaces to MIME types. Each line contains three fields, the namespace, the localName and the MIME type. Each field is separated by a space. If the localName is empty, then there are two spaces between the namespace and the MIME type.

  This file is also generated by the update-mime-database application.

`<MIME>/aliases`

- Contains a list of aliases for each MIME type. An alias is simply a MIME type that is sometimes known as another type. For each line in this file there are two fields: the first field is the alias name, and the second field is the MIME type. The fields are separated by a space.

  This file is also generated by the update-mime-database application.

`<MIME>/subclasses`

- Contains a list of subclassed MIME types and their parent MIME type. From the XDG shared mime specification:

  > A type is a subclass of another type if any instance of the first type is also an instance of the second. For example, all image/svg files are also text/xml, text/plain and application/octet-stream files. Subclassing is about the format, rather than the catagory of the data (for example, there is no 'generic spreadsheet' class that all spreadsheets inherit from).

  The format of this file is similar to the `aliases` file. Each line contains two fields, where the first field is the subclassed MIME type and the second field is the parent MIME type. Each field is separated by a space.

  This file is also generated by the update-mime-database application.

### Refreshing the MIME Database

Understanding how to refresh the MIME database is important for administrators who wish to add new MIME types to the system, or otherwise modify information about a MIME type. The application update-mime-database is intended for this purpose.

For example, if an application installs information about a new MIME type to `/usr/share/mime/packages/diff.xml`, then update-mime-database must be called with the parameter `/usr/share/mime`.

    # update-mime-database /usr/share/mime
    ***
    * Updating MIME database in /usr/share/mime...
    ***

The MIME database is refreshed by scanning all the source XML files in the directory `<MIME>/packages`.

## The source XML files

Located in the `<MIME>/packages` directory, these XML files provide all the information regarding MIME types that is installed into the database by the update-mime-database application. There are a few rules about the XML file itself:

- It must specify the namespace as `http://www.freedesktop.org/standards/shared-mime-info`

- The root element must be `mime-info`

- Zero or more `mime-type` elements can be specified as children of the `mime-info` element. The `type` attribute is used to specify the MIME type that is being defined.

By default, the `freedesktop.org.xml` file is installed to the `packages` directory in one of the `<MIME>` paths (usually `/usr/share/mime/packages`).

mimetypes-mimeinfo-elements gives a brief description for each of the elements that can occur as children to the `mime-type` element.

## Child elements of `<mime-type>`

Element (and attributes) | Description
`<glob pattern="`*.xyz`">` | This element specifies a glob pattern against filenames. If the filename matches, then it is assigned the MIME type of the parent `mime-type` element. The `pattern` attribute is mandatory.
`<magic priority="`50`">` | This element contains a list of `match` elements as its children. The `priority` attribute is optional, and specifies a priority between 0 and 100, with 100 being the highest matching priority. Each child `match` element has three required attributes: `type` `offset` `value` and a fourth optional attribute, `mask`. For details on these attributes, see the XDG shared mime info specification.
`<alias type="`media`/`subtype`">` | This element defines an alias for the parent `mime-type` element. An alias is simply a MIME type that is sometimes known as another type. For example, `application/x-pdf` is an alias for the MIME type `application/pdf`.
`<sub-class-of type="`media`/`subtype`">` | This element defines the parent `mime-type` element as a subclass of the MIME type specified in the `type` attribute. For example, `image/svg` is a sub class of the MIME type `text/xml`, `text/plain`, and `application/octet-stream`.
`<comment xml:lang="`locale`">` | This element provides a human readable description for the MIME type. There can be zero or more occurrences of this element as long as each one contains a unique value for the `xml:lang` attribute.
`<root-XML namespaceURI="`namespace`" localName="">` | If a file is determined to an XML file, then this element helps to further classify it through the use of the `namespaceURI` and `localName` attributes, both of which are required. The attribute `namespaceURI` is the namespace of the document, and `localName` is the name of the root element for the document. If `localName` is present but its value is empty, then the root element may have any name, but the namespace must still match.

The easiest way to understand these files is to take a look at an example. Borrowing from the XDG shared mime specification, mimetypes-source-xml-example displays the contents of a source XML file called `diff.xml`. This example defines the MIME type `text/x-diff`. There are multiple `comment` elements which give a human readable name to the MIME type in a number of different languages. This MIME type has both rules for matching through glob patterns and through the use of content sniffing (better known as `magic` rules). Any file with the extension `.diff` or `.patch` will resolve to this MIME type. Additionally any file whose contents start with the strings specified in the `value` attributes of the `match` element, will resolve to the `text/x-diff` MIME type.

The order in which glob patterns and magic rules apply is beyond the scope of this document. For details on this, see the XDG shared mime info specification.

### Example of a source XML file: `diff.xml`

    <?xml version='1.0'?>
    <mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'>
      <mime-type type="text/x-diff">
        <comment>Differences between files</comment>
        <comment xml:lang="af">verskille tussen lêers</comment>
        <!-- more translated comment elements -->
        <magic priority="50">
          <match type="string" offset="0" value="diff\t"/>
          <match type="string" offset="0" value="***\t"/>
          <match type="string" offset="0" value="Common subdirectories: "/>
        </magic>
        <glob pattern="*.diff"/>
        <glob pattern="*.patch"/>
      </mime-type>
    </mime-info>

## Modifying MIME types

You should never directly modify the source XML files that are installed to the `<MIME>/packages` directory by applications. Instead, modify the `Overrides.xml` file. This file has precedence over all other source XML files installed into the same `packages` directory. If you are an application author, then this rule does not apply. You should create a new source XML file and place it in the proper `<MIME>/packages` directory (your `Makefile` will take care of this, of course).

You can modify the MIME database for all users on the system or for a particular user depending on the location of the file you change. To modify the database for all users, make changes to the file `Overrides.xml` in the `$XDG_DATA_DIRS/mime/packages` directory. To modify the database for a single user, make changes to the file `Overrides.xml` in the `$XDG_DATA_HOME/mime/packages` directory.

After changes are made, you must always run the update-mime-database application, with the directory location of the MIME database as the first parameter.

### Adding or Modifying MIME types

To add one or more MIME types for all users:

1. Create or modify an existing `Overrides.xml` source XML file, containing the definitions for the MIME types. For more information, see mimetypes-source-xml.

2. Place the `Overrides.xml` file in the `/usr/share/mime/packages` directory.

3. Update the MIME database by running update-mime-database using the system account.

       update-mime-database /usr/share/mime

To add one or more MIME types for a single user, follow the same steps, except place your `Overrides.xml` file in the `~/.local/share/mime/packages` directory. Additionally, call update-mime-database with `~/.local/share/mime/packages` as the first parameter.

### Verifying Changes

After you have made a change to the MIME database and refreshed its contents, you can verify that the change has taken effect using the gnomevfs-info application. This application prints the MIME type and other useful information about a file.

Running gnomevfs-info on a SVG file gives you the output shown below. You'll notice the default application for this MIME type is `eog.desktop`; We will discuss default applications in mimetypes-registering.

    $ gnomevfs-info mime-diagram.svg
    Name              : mime-diagram.svg
    Type              : Regular
    MIME type         : image/svg+xml
    Default app       : eog.desktop
    Size              : 14869
    Blocks            : 32
    I/O block size    : 4096
    Local             : YES
    SUID              : NO
    SGID              : NO
    Sticky            : NO
    Permissions       : 600644
    Link count        : 1
    UID               : 1000
    GID               : 100
    Access time       : Wed Feb 22 18:24:47 2006
    Modification time : Wed Feb 22 18:24:42 2006
    Change time       : Wed Feb 22 18:24:42 2006
    Device #          : 775
    Inode #           : 297252
    Readable          : YES
    Writable          : YES
    Executable        : NO
    $

mimetypes-newtype-example walks through the steps of creating a new MIME type and then verifying the changes using gnomevfs-info.

### `application/x-newtype` Example

To create (or override) a MIME type and verify the changes:

1. Make a new, empty file in your home directory called `testing.xyz`.

2. Use gnomevfs-info on the file to find out the MIME type.The MIME type for this file should be detected as `text/plain` because there are not any glob patterns or magic rules that match it

   When no glob patterns or magic rules match a file, then it is resolved to the MIME type `text/plain` if it contains textual data or `application/octet-stream` for binary data. If the file is empty, then it defaults to `text/plain`.

   .

3. Create (or modify) the `Overrides.xml` file as described in mimetypes-addmodify with the contents given in mimetypes-overrides-xml.

4. Refresh the database using update-mime-database.

5. Use gnomevfs-info to verify that your change has taken effect. You should see the MIME type for the `testing.xyz` file resolved as `application/x-newtype`.

       $ gnomevfs-info testing.xyz | grep MIME
       MIME type         : application/x-newtype
       $

#### `Overrides.xml` file

    <?xml version='1.0' encoding='utf-8'?>
    <mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
      <mime-type type="application/x-newtype"><comment>new mime type</comment><glob pattern="*.xyz"/></mime-type>
    </mime-info>

## Registering Applications for MIME Types

Registering applications to handle MIME types is fairly straightforward. Applications are registered by creating a `MimeType` key in their `.desktop` entry file and listing each MIME type separated by a semicolon. The `MimeType` key should only be used in `.desktop` files whose `Type` key has the value `Application`. For more information on `.desktop` files, see menustructure-desktopentry.

After creating or modifying a `.desktop` entry file, you must update the application database using the update-desktop-database application (very similar to update-mime-database, except it does not take a parameter). This will create a `mimeinfo.cache` file in the `applications` subdirectory for each directory in `$XDG_DATA_HOME:$XDG_DATA_DIRS`. The cache file is necessary so that all the `.desktop` files do not need to be scanned for just the `MimeType` key, as this causes unnecessary disk I/O.

Default applications to use for specific MIME types should be specified in a file called `defaults.list`. This file is located in the `applications` subdirectory for each directory in `$XDG_DATA_HOME` and `$XDG_DATA_DIRS`. The format for this file consists of the MIME type, the `=` symbol and the Desktop File ID (which is the filename for the desktop entry file). mimetypes-registering-example is a short example of a `defaults.list` file in a user's `~/.local/share/applications` directory.

### A User's `defaults.list` file

    [Default Applications]
    application/pdf=evince.desktop
    text/html=epiphany.desktop
    text/plain=gedit.desktop
    image/jpeg=eog.desktop
    image/png=eog.desktop
    text/xml=gedit.desktop

### XDG Desktop Entry Specification

How to register MIME types for applications is part of the XDG desktop entry specification, rather than the XDG shared mime info specification.

## Adding an Application to the GNOME Desktop

To add an application to the GNOME Desktop, perform the following steps:

1. Add a menu item for the application. For more information on how to add an item to a menu, see menustructure-2.

2. Add an icon for the application to `/usr/share/icons/`theme-name`/`icon-size`/apps`. For more information on icons and themes, see themes-11.

3. If the application uses a new MIME type, add a source XML file to the MIME database. For more information, see mimetypes-modifying.

4. If the application uses a new MIME type, add an icon for the MIME type to `/usr/share/icons/`theme-name`/`icon-size`/mimetypes`. For more information on icons and themes, see themes-0.

5. To associate the application with a MIME type, include a `MimeType` key in your `.desktop` file. For more information, see mimetypes-registering.