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
MIME types
introduction
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
MIME types
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 .
<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
MIME types
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).
gives a brief
description for each of the elements that can occur as children to the
mime-type element.
Child elements of <mime-info>
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,
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
MIME types
verifying changes
MIME types
modifying
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:
Create or modify an existing
Overrides.xml source XML file, containing the
definitions for the MIME types. For more information, see .
Place the Overrides.xml file in the
/usr/share/mime/packages directory.
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 .
$ 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
$
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:
Make a new, empty file in your home directory called
testing.xyz.
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.
.
Create (or modify) the Overrides.xml file
as described in with the
contents given in .
Refresh the database using
update-mime-database.
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
MIME types
registering applications for
applications
registry
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 .
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). 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
MIME types
adding applications
applications
adding
To add an application to the GNOME Desktop, perform the following
steps:
Add a menu item for the application. For more information on how
to add an item to a menu, see .
Add an icon for the application to
/usr/share/icons/theme-name/icon-size/apps.
For more information on icons and themes, see .
If the application uses a new MIME type, add a source XML file
to the MIME database. For more information, see .
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 .
To associate the application with a MIME type, include a
MimeType key in your .desktop
file. For more information, see .