Filesystem Hierarchy Standard

4.11 /usr/share : Architecture-independent data

4.11.1 Purpose

The /usr/share hierarchy is for all read-only architecture independent data files.[footnote 25]

This hierarchy is intended to be shareable among all architecture platforms of a given OS; thus, for example, a site with i386, Alpha, and PPC platforms might maintain a single /usr/share directory that is centrally-mounted. Note, however, that /usr/share is generally not intended to be shared by different OSes or by different releases of the same OS.

Any program or package which contains or requires data that doesn't need to be modified should store that data in /usr/share (or /usr/local/share, if installed locally). It is recommended that a subdirectory be used in /usr/share for this purpose.

Game data stored in /usr/share/games must be purely static data. Any modifiable files, such as score files, game play logs, and so forth, should be placed in /var/games.

4.11.2 Requirements

The following directories, or symbolic links to directories, must be in /usr/share

"/usr/share"
man
misc
"Architecture-independent data"
Online manuals
Miscellaneous architecture-independent data

Tree 4.11.2.1

4.11.3 Specific Options

The following directories, or symbolic links to directories, must be in /usr/share, if the corresponding subsystem is installed:

"/usr/share"
dict
doc
games
info
locale
nls
sgml
terminfo
tmac
zoneinfo
"Architecture-independent data"
Word lists (optional)
Miscellaneous documentation (optional)
Static data files for /usr/games (optional)
GNU Info system's primary directory (optional)
Locale information (optional)
Message catalogs for Native language support (optional)
SGML and XML data (optional)
Directories for terminfo database (optional)
troff macros not distributed with groff (optional)
Timezone information and configuration (optional)

Tree 4.11.3.2

It is recommended that application-specific, architecture-independent directories be placed here. Such directories include groff, perl, ghostscript, texmf, and kbd (Linux) or syscons (BSD). They may, however, be placed in /usr/lib for backwards compatibility, at the distributor's discretion. Similarly, a /usr/lib/games hierarchy may be used in addition to the /usr/share/games hierarchy if the distributor wishes to place some game data there.

4.11.4 /usr/share/dict : Word lists (optional)

4.11.4.1 Purpose

This directory is the home for word lists on the system; Traditionally this directory contains only the English words file, which is used by look(1) and various spelling programs. words may use either American or British spelling.
BEGIN RATIONALE

The reason that only word lists are located here is that they are the only files common to all spell checkers.
END RATIONALE

4.11.4.2 Specific Options

The following files, or symbolic links to files, must be in /usr/share/dict, if the corresponding subsystem is installed:

words List of English words (optional)

Table 4.11.4.2.1

Sites that require both American and British spelling may link words to /usr/share/dict/american-english or /usr/share/dict/british-english.

Word lists for other languages may be added using the English name for that language, e.g., /usr/share/dict/french, /usr/share/dict/danish, etc. These should, if possible, use an ISO 8859 character set which is appropriate for the language in question; if possible the Latin1 (ISO 8859-1) character set should be used (this is often not possible).

Other word lists must be included here, if present.

4.11.5 /usr/share/man : Manual pages

4.11.5.1 Purpose

This section details the organization for manual pages throughout the system, including /usr/share/man. Also refer to the section on /var/cache/man.

The primary <mandir> of the system is /usr/share/man. /usr/share/man contains manual information for commands and data under the / and /usr filesystems.[footnote 26]

Manual pages are stored in <mandir>/<locale>/man<section>/<arch>. An explanation of <mandir>, <locale>, <section>, and <arch> is given below.

A description of each section follows:

4.11.5.2 Specific Options

The following directories, or symbolic links to directories, must be in /usr/share/<mandir>/<locale>, unless they are empty:[footnote 28]

"<mandir>/<locale>"
man1
man2
man3
man4
man5
man6
man7
man8
"A manual page hierarchy"
User programs (optional)
System calls (optional)
Library calls (optional)
Special files (optional)
File formats (optional)
Games (optional)
Miscellaneous (optional)
System administration (optional)

Tree 4.11.5.2.3

The component <section> describes the manual section.

Provisions must be made in the structure of /usr/share/man to support manual pages which are written in different (or multiple) languages. These provisions must take into account the storage and reference of these manual pages. Relevant factors include language (including geographical-based differences), and character code set.

This naming of language subdirectories of /usr/share/man is based on Appendix E of the POSIX 1003.1 standard which describes the locale identification string -- the most well-accepted method to describe a cultural environment. The <locale> string is:

<language>[_<territory>][.<character-set>][,<version>]

The <language> field must be taken from ISO 639 (a code for the representation of names of languages). It must be two characters wide and specified with lowercase letters only.

The <territory> field must be the two-letter code of ISO 3166 (a specification of representations of countries), if possible. (Most people are familiar with the two-letter codes used for the country codes in email addresses.[footnote 29]) It must be two characters wide and specified with uppercase letters only.

The <character-set> field must represent the standard describing the character set. If the <character-set> field is just a numeric specification, the number represents the number of the international standard describing the character set. It is recommended that this be a numeric representation if possible (ISO standards, especially), not include additional punctuation symbols, and that any letters be in lowercase.

A parameter specifying a <version> of the profile may be placed after the <character-set> field, delimited by a comma. This may be used to discriminate between different cultural needs; for instance, dictionary order versus a more systems-oriented collating order. This standard recommends not using the <version> field, unless it is necessary.

Systems which use a unique language and code set for all manual pages may omit the <locale> substring and store all manual pages in <mandir>. For example, systems which only have English manual pages coded with ASCII, may store manual pages (the man<section> directories) directly in /usr/share/man. (That is the traditional circumstance and arrangement, in fact.)

Countries for which there is a well-accepted standard character code set may omit the <character-set> field, but it is strongly recommended that it be included, especially for countries with several competing standards.

Various examples:

Language Territory Character Set Directory
English -- ASCII /usr/share/man/en
English United Kingdom ASCII /usr/share/man/en_GB
English United States ASCII /usr/share/man/en_US
French Canada ISO 8859-1 /usr/share/man/fr_CA
French France ISO 8859-1 /usr/share/man/fr_FR
German Germany ISO 646 /usr/share/man/de_DE.646
German Germany ISO 6937 /usr/share/man/de_DE.6937
German Germany ISO 8859-1 /usr/share/man/de_DE.88591
German Switzerland ISO 646 /usr/share/man/de_CH.646
Japanese Japan JIS /usr/share/man/ja_JP.jis
Japanese Japan SJIS /usr/share/man/ja_JP.sjis
Japanese Japan UJIS (or EUC-J) /usr/share/man/ja_JP.ujis

Table 4.11.5.2.2

Similarly, provision must be made for manual pages which are architecture-dependent, such as documentation on device-drivers or low-level system administration commands. These must be placed under an <arch> directory in the appropriate man<section> directory; for example, a man page for the i386 ctrlaltdel(8) command might be placed in /usr/share/man/<locale>/man8/i386/ctrlaltdel.8.

Manual pages for commands and data under /usr/local are stored in /usr/local/man. Manual pages for X11R6 are stored in /usr/X11R6/man. It follows that all manual page hierarchies in the system must have the same structure as /usr/share/man.

The cat page sections (cat<section>) containing formatted manual page entries are also found within subdirectories of <mandir>/<locale>, but are not required nor may they be distributed in lieu of nroff source manual pages.

The numbered sections "1" through "8" are traditionally defined. In general, the file name for manual pages located within a particular section end with .<section>.

In addition, some large sets of application-specific manual pages have an additional suffix appended to the manual page filename. For example, the MH mail handling system manual pages must have mh appended to all MH manuals. All X Window System manual pages must have an x appended to the filename.

The practice of placing various language manual pages in appropriate subdirectories of /usr/share/man also applies to the other manual page hierarchies, such as /usr/local/man and /usr/X11R6/man. (This portion of the standard also applies later in the section on the optional /var/cache/man structure.)

4.11.6 /usr/share/misc : Miscellaneous architecture-independent data

This directory contains miscellaneous architecture-independent files which don't require a separate subdirectory under /usr/share.

4.11.6.1 Specific Options

The following files, or symbolic links to files, must be in /usr/share/misc, if the corresponding subsystem is installed:

ascii ASCII character set table (optional)
magic Default list of magic numbers for the file command (optional)
termcap Terminal capability database (optional)
termcap.db Terminal capability database (optional)

Table 4.11.6.1.3

Other (application-specific) files may appear here,[footnote 30] but a distributor may place them in /usr/lib at their discretion.

4.11.7 /usr/share/sgml : SGML and XML data (optional)

4.11.7.1 Purpose

/usr/share/sgml contains architecture-independent files used by SGML or XML applications, such as ordinary catalogs (not the centralized ones, see /etc/sgml), DTDs, entities, or style sheets.

4.11.7.2 Specific Options

The following directories, or symbolic links to directories, must be in /usr/share/sgml, if the corresponding subsystem is installed:

"/usr/share/sgml"
docbook
tei
html
mathml
"SGML and XML data"
docbook DTD (optional)
tei DTD (optional)
html DTD (optional)
mathml DTD (optional)

Tree 4.11.7.2.4

Other files that are not specific to a given DTD may reside in their own subdirectory.

[25] Much of this data originally lived in /usr (man, doc) or /usr/lib (dict, terminfo, zoneinfo).

[26] Obviously, there are no manual pages in / because they are not required at boot time nor are they required in emergencies.[footnote 27]

[27] Really.

[28] For example, if /usr/local/man has no manual pages in section 4 (Devices), then /usr/local/man/man4 may be omitted.

[29] A major exception to this rule is the United Kingdom, which is `GB' in the ISO 3166, but `UK' for most email addresses.

[30] Some such files include:


Previous: /usr/sbin : Non-essential standard system binaries
Next: /usr/src : Source code (optional)
Up: Table of Contents

Translated by troff2html v1.5 on 29 March 2002 by Daniel Quinlan