The /usr Hierarchy

/usr is the second major section of the filesystem. /usr is shareable, read-only data. That means that /usr should be shareable between various FHS-compliant hosts and must not be written to. Any information that is host-specific or varies with time is stored elsewhere.

Large software packages must not use a direct subdirectory under the /usr hierarchy.

The following directories, or symbolic links to directories, are required in /usr.

Directory Description
bin Most user commands
include Header files included by C programs
lib Libraries
local Local hierarchy (empty after main installation)
sbin Non-vital system binaries
share Architecture-independent data

Directory Description
X11R6 XWindow System, version 11 release 6 (optional)
games Games and educational binaries (optional)
lib<qual> Alternate Format Libraries (optional)
src Source code (optional)

An exception is made for the X Window System because of considerable precedent and widely-accepted practice.

The following symbolic links to directories may be present. This possibility is based on the need to preserve compatibility with older systems until all implementations can be assumed to use the /var hierarchy. 

    /usr/spool -> /var/spool
    /usr/tmp -> /var/tmp
    /usr/spool/locks -> /var/lock

Once a system no longer requires any one of the above symbolic links, the link may be removed, if desired.

This hierarchy is reserved for the X Window System, version 11 release 6, and related files.

To simplify matters and make XFree86 more compatible with the X Window System on other systems, the following symbolic links must be present if /usr/X11R6 exists: 

    /usr/bin/X11 -> /usr/X11R6/bin
    /usr/lib/X11 -> /usr/X11R6/lib/X11
    /usr/include/X11 -> /usr/X11R6/include/X11

In general, software must not be installed or managed via the above symbolic links. They are intended for utilization by users only. The difficulty is related to the release version of the X Window System - in transitional periods, it is impossible to know what release of X11 is in use.

Host-specific data in /usr/X11R6/lib/X11 should be interpreted as a demonstration file. Applications requiring information about the current host must reference a configuration file in /etc/X11, which may be linked to a file in /usr/X11R6/lib.

This is the primary directory of executable commands on the system.

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

Directory Description
mh Commands for the MH mail handling system (optional)

/usr/bin/X11 must be a symlink to /usr/X11R6/bin if the latter exists.

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

Command Description
perl The Practical Extraction and Report Language (optional)
python The Python interpreted language (optional)
tclsh Simple shell containing Tcl interpreter (optional)
wish Simple Tcl/Tk windowing shell (optional)
expect Program for interactive dialog (optional)

Because shell script interpreters (invoked with #!<path> on the first line of a shell script) cannot rely on a path, it is advantageous to standardize their locations. The Bourne shell and C-shell interpreters are already fixed in /bin, but Perl, Python, and Tcl are often found in many different places. They may be symlinks to the physical location of the shell interpreters.

This is where all of the system's general-use include files for the C programming language should be placed.

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

Directory Description
bsd BSD compatibility include files (optional)

The symbolic link /usr/include/X11 must link to /usr/X11R6/include/X11 if the latter exists.

/usr/lib includes object files, libraries, and internal binaries that are not intended to be executed directly by users or shell scripts.

Applications may use a single subdirectory under /usr/lib. If an application uses a subdirectory, all architecture-dependent data exclusively used by the application must be placed within that subdirectory.

For historical reasons, /usr/lib/sendmail must be a symbolic link to /usr/sbin/sendmail if the latter exists.

If /lib/X11 exists, /usr/lib/X11 must be a symbolic link to /lib/X11, or to whatever /lib/X11 is a symbolic link to.

/usr/lib<qual> performs the same role as /usr/lib for an alternate binary format, except that the symbolic links /usr/lib<qual>/sendmail and /usr/lib<qual>/X11 are not required.

The /usr/local hierarchy is for use by the system administrator when installing software locally. It needs to be safe from being overwritten when the system software is updated. It may be used for programs and data that are shareable amongst a group of hosts, but not found in /usr.

Locally installed software must be placed within /usr/local rather than /usr unless it is being installed to replace or upgrade software in /usr.

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

Directory Description
bin Local binaries
etc Host-specific system configuration for local binaries
games Local game binaries
include Local C header files
lib Local libraries
man Local online manuals
sbin Local system binaries
share Local architecture-independent hierarchy
src Local source code

No other directories, except those listed below, may be in /usr/local after first installing a FHS-compliant system.

If directories /lib<qual> or /usr/lib<qual> exist, the equivalent directories must also exist in /usr/local.

/usr/local/etc may be a symbolic link to /etc/local.

The consistency of /usr/local/etc is beneficial to installers, and is already used in other systems. As all of /usr/local needs to be backed up to reproduce a system, it introduces no additional maintenance overhead, but a symlink to /etc/local is suitable if systems want alltheir configuration under one hierarchy.

Note that /usr/etc is still not allowed: programs in /usr should place configuration files in /etc.

The requirements for the contents of this directory are the same as /usr/share. The only additional constraint is that /usr/local/share/man and /usr/local/man directories must be synonomous (usually this means that one of them must be a symbolic link).

This directory contains any non-essential binaries used exclusively by the system administrator. System administration programs that are required for system repair, system recovery, mounting /usr, or other essential functions must be placed in /sbin instead.

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

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.

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

Directory Description
man Online manuals
misc Miscellaneous architecture-independent data

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

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

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.

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.

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

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

File Description
words List of English words (optional)

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.

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.

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:

  • man1: User programs Manual pages that describe publicly accessible commands are contained in this chapter. Most program documentation that a user will need to use is located here.

  • man2: System calls This section describes all of the system calls (requests for the kernel to perform operations).

  • man3: Library functions and subroutines Section 3 describes program library routines that are not direct calls to kernel services. This and chapter 2 are only really of interest to programmers.

  • man4: Special files Section 4 describes the special files, related driver functions, and networking support available in the system. Typically, this includes the device files found in /dev and the kernel interface to networking protocol support.

  • man5: File formats The formats for many data files are documented in the section 5. This includes various include files, program output files, and system files.

  • man6: Games This chapter documents games, demos, and generally trivial programs. Different people have various notions about how essential this is.

  • man7: Miscellaneous Manual pages that are difficult to classify are designated as being section 7. The troff and other text processing macro packages are found here.

  • man8: System administration Programs used by system administrators for system operation and maintenance are documented here. Some of these programs are also occasionally useful for normal users.

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

Directory Description
man1 User programs (optional)
man2 System calls (optional)
man3 Library calls (optional)
man4 Special files (optional)
man5 File formats (optional)
man6 Games (optional)
man7 Miscellaneous (optional)
man8 System administration (optional)

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.) 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 ISO 8859-15 /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

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.)

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

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

File Description
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)

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

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

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

Directory Description
docbook docbook DTD (optional)
tei tei DTD (optional)
html html DTD (optional)
mathml mathml DTD (optional)

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

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

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

Directory Description
docbook docbook XML DTD (optional)
xhtml XHTML DTD (optional)
mathml MathML DTD (optional)

Source code may be place placed in this subdirectory, only for reference purposes.