filesystem - csc.kth.semaandree/doc/filesystem.pdffilesystem Filesystem hierarchy implementation for GNU/Pony by Mattias Andr´ee (maandree)

filesystemFilesystem hierarchy implementation for GNU/Pony

by Mattias Andree (maandree)

Copyright c© 2013, 2014 Mattias Andree

Permission is granted to copy, distribute and/or modify this document under theterms of the GNU Free Documentation License, Version 1.3 or any later versionpublished by the Free Software Foundation; with no Invariant Sections, with noFront-Cover Texts, and with no Back-Cover Texts. A copy of the license is includedin the section entitled “GNU Free Documentation License”.

i

Table of Contents

1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Foundamental hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22.1 / . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22.2 lost+found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22.3 /mnt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22.4 /media . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22.5 /root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22.6 /home . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.7 /info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.8 /shared . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 Interface hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43.1 /dev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43.2 /dev/pts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43.3 /dev/shm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43.4 /proc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43.5 /run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43.6 /sys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

4 Settings hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54.1 /boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54.2 /etc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54.3 /etc/alternatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54.4 /etc/opt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54.5 /etc/skel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

5 Variable data hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65.1 /srv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65.2 /srv/db . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65.3 /srv/ftp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65.4 /srv/http . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65.5 /tmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65.6 /var . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65.7 /var/tmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65.8 /var/cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65.9 /var/spool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65.10 /var/opt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65.11 /var/log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65.12 /var/mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65.13 /var/games . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75.14 /var/lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75.15 /var/lib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75.16 /var/local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75.17 /var/empty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75.18 /run/lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

ii

6 Primary hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86.1 /bin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86.2 /sbin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86.3 /lib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86.4 /opt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

7 Secondary hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97.1 /usr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97.2 /usr/bin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97.3 /usr/sbin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97.4 /usr/games . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97.5 /usr/libexec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97.6 /usr/lib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97.7 /usr/include . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107.8 /usr/src . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107.9 /usr/doc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107.10 /usr/share . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107.11 /usr/share/applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107.12 /usr/share/changelogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107.13 /usr/share/licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107.14 /usr/share/misc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107.15 /usr/share/info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117.16 /usr/share/man . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117.17 /usr/share/dict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

8 Tertiary hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

9 User hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139.1 ~/.config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139.2 ~/.cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139.3 ~/.spool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139.4 ~/.local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

10 Simplified hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410.1 /localhost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410.2 /localhost/users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410.3 /localhost/temporary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410.4 /localhost/applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1510.5 /localhost/system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1510.6 /localhost/system/essentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1610.7 /localhost/system/applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1610.8 /localhost/host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1710.9 /localhost/host/system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

11 Further simplified hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Appendix A GNU Free Documentation License . . . . . . . . . . . . . 20

Chapter 1: Overview 1

1 Overview

filesystem is a system base package that provides a implementation of a filesystem hierarchyby creating directories and symbolic directories, as well as providing files required for a systemrun but is not owned by any other package.

filesystem also specifies directory permissions and ownerships so other packages can beagnostic and not implement this themself.

The filesystem hierarchy is based on the Filesystem Hierarchy Standard developed by theLinux Foundation.

Chapter 2: Foundamental hierarchy 2

2 Foundamental hierarchy

2.1 /

/ is top-most directory, there is a parition mounted on it, and it is a very you ultimately findeverything, even other paritions.

/ is called “root”, which may cause confusion is try to call it / when possible or even “slash”if things get really confusing.

2.2 lost+found

lost+found (‘”lost and found”) is a directory create by most filesystems, and you may find oneat any mount point1, including /lost+found, /mnt/lost+found and /media/*/lost+found.

When a filesystem finds an orphaned inode, that is, a file without any known file names, itmay put it in its lost+found

If you do not which to this file in your removable devices, you can normally, dependingon your file manager, add a file named .hidden (the perfix dot means that it will be hidden)containing a line with the text lost+found, in the device’s mount point.

2.3 /mnt

/mnt (“mount”) is a directory that is just there for your convience, it is intended to be usedas a mount point for a file system, normally a removable device, that you are working withtemporarly, and is not intended to be mounted long term.

2.4 /media

/media as a superdirectory of long term mount points, more specifically, it is intended to onlycontain directories that are used as mount points for long term mounted filesystems that is notincorporated into the remaining part of the filesystem hierarchy.

For example, if you have an external drive named “oggcasts”, you can create the directory/media/oggcasts, onto which you mount the partion you have on the “oggcast” drive.

It is also intended for use of optical storage, floppy drives, zip drived and alike, if you arestill using any of those.

2.5 /root

/root (“root” or “slash root”) is the home directory for the system administrator, the user root.Normally there is no much point to have a home directory for the system administrator as thatis not any user intended for use beyond administrations. However, it will contian applicationconfigurations if the user chooses to have any, and can also be used to store files needed foradministration, that you do not want to be clutter up your non-root user home directory.

Theoretically it is possile to symlink /root to your user home directory so you do not needto separately configure the root user. This paractice is however unrecommended, as messingup your user could potentially mess up the root user as well; rather, you should keep your rootconfigurations as safe and minimalisic as possible.

1 A directory onto which a file system is mounted

Chapter 2: Foundamental hierarchy 3

2.6 /home

/home (“home” or “slash home”) is the default superdirectory for non-root user home directories.When you create a new user, if not otherwise specified, the new user, named zyzzx, will becreated a the directory /home/zyzzx which will be set to zyzzx’s home directory and onlyzyzzx and root will have access to it.

2.7 /info

/info (“info” or “information”) is a GNU/Pony extension to the filesystem hierarchy inspiredby the filesystem hierarchy found at the Royal Insitute of Technology.

By default only root have write access to /info, but you may want to change the group tofaculty (or similarily) and give write access to the group.

/info is intended for privileged users to publish files, and is thus fairly unneccessary forsingle user computers unless you give your friends SFTP access.

2.8 /shared

/shared (“sharing is magic”)2 is a GNU/Pony extension to the filesystem hierarchy. It isintended for user shared files. While users are recommended to create a directory ~/Public andgive everypony read access to it, and store personal non-private files in it for other ponies toread or cannibalise, /shared is intended for all users to use together for non-personal data, forexample, you can put your radio shows, music, books or whatever, there.

2 Or “slash shared” or just “shared”

Chapter 3: Interface hierarchy 4

3 Interface hierarchy

3.1 /dev

/dev is a mount point for the kernel advanced programming interface filesystem for devices andpseudodevices.

3.2 /dev/pts

/dev/pts is a mount point for the kernel advanced programming interface filesystem for pseu-doterminals.

3.3 /dev/shm

/dev/shm is a mount point for the kernel advanced programming interface filesystem for sharedmemory, but can also be used as a directory for temporary files that will always be in randomaccess memory.

3.4 /proc

/proc is a mount point for the kernel advanced programming interface filesystem for informationabout processes. It does contain some miscellany, but it also cotains one directory for eachprocess named as the process ID as well as one special symlink, named /proc/self pointing tothe directory for the current process.

3.5 /run

/run is a mount point for the advanced programming interface filesystem for run-time variabledata. It contains system information describing the system since it was booted. Programs mayhave subdirectories; process identifiers and UNIX-domain sockets used by programs should beplaced in this file system.

3.6 /sys

/sys is a mount point for the kernel advanced programming interface filesystem for kernel andhardware access and modification.

Chapter 4: Settings hierarchy 5

4 Settings hierarchy

4.1 /boot

/boot is the mount point for the partition that the bootmanager starts and contains the boot-loader that boots an operativing system.

/boot contains all bootable kernels and initramfs:es that are not booted by a chainloadedbootloaders; it also contains settings for your bootloader and tools your can run, instead of youroperativing system, for diagnositics.

4.2 /etc

/etc (pronounced however you wish) the directory for system-wide host-specific configurations.

4.3 /etc/alternatives

/etc/alternatives is a directory that contain symlinks. Each symlink, is named as a com-mon, for example sh, and that command is a symlink to that symlink. The symlinks inthis directory may point to the actual command that provides them. For example, /bin/shshould point to /etc/alternatives/sh which in turn may point to /bin/bash, but itsbetter if it points to /etc/alternatives.providers/sh/bash which points to /bin/bash./etc/alternatives.providers is a related directory that contains directories named as com-mands. These directories contains symlinks named as the packages that can provide them andpoints the their corresponding commands.

4.4 /etc/opt

/etc/opt the directory for system-wide host-specific configurations for programs installed to/opt.

4.5 /etc/skel

/etc/skel is the user home directory skeletion (prototype), that is copyed to new users whenthey are created.

Chapter 5: Variable data hierarchy 6

5 Variable data hierarchy

5.1 /srv

/srv is a superdirectory for data provided by services hosted on the machine.

5.2 /srv/db

/srv/db is a directory for data provided by databases hosted on the machine. /srv/db shouldnot directly contain database data, but rather a directory named as the service, that in turncontians the database files.

5.3 /srv/ftp

/srv/db is the directory for files provided by a FTP server on the machine.

5.4 /srv/http

/srv/http is the directory for files provided by a HTTP server on the machine.

5.5 /tmp

/tmp is the directory for temporary files stored primarly in the random access memory, butcould potentially also be stored on a swap partition.

5.6 /var

/var is root directory for variable data outside /srv and /tmp.

5.7 /var/tmp

/var/tmp is the directory for temporary files stored on the drive and will be preserved betweensystem boots.

5.8 /var/cache

/var/cached is the directory cached files, that is temporary files used by a program, but canbe removed at any time.

5.9 /var/spool

/var/cached is the directory spool files, that is temporary files used by a program, but cannotsafely be removed and will be removed by the program when it is no longer needed.

5.10 /var/opt

/var/opt is the directory file variable data for programs located in /opt and should be ar-ranged in the same when. The program may arrange the data in its directory as it wish, but isrecommended to arrange it in the same way as /var is arranged.

5.11 /var/log

/var/log is the directory of system logs.

5.12 /var/mail

/var/mail is the directory of user e-mail fetched by a e-mail service.

Chapter 5: Variable data hierarchy 7

5.13 /var/games

/var/games is the directory of variable game data, such as high scores.

5.14 /var/lock

/var/lock is the directory of file locks, if you want the locks be cleared at reboot it fits betterin /run/lock.

5.15 /var/lib

/var/lib is the directory of program and system state data.

5.16 /var/local

/var/local is the /var directory of programs located in /usr/local, contains the analogousdirectories cache, spool, games, lock and lib.

5.17 /var/empty

/var/empty is a directory that should be empty, that services can chroot instances into to hidethe file system.

5.18 /run/lock

/run/lock is just like /var/lock, except the lock files will be cleared at reboot.

Chapter 6: Primary hierarchy 8

6 Primary hierarchy

6.1 /bin

/bin is the directory for commands needed for system maintenance. This does include commandyou will use regulary everyday, but not all of them, just the ones you would also need for normalsystem maintenance and rescue.

6.2 /sbin

/sbin is the directory for essential binaries used system modifications and interaction. While bindirectories contains normal everyday commands, sbin directories contains commands normallyused by the system initialisation, but primarly system daemons, commands for hardware andsystem setup, and similar commands, take a peek in for a better understanding.

6.3 /lib

/lib is the directory for libraries used by commands in /bin and /sbin, but is also containsexecutable non-commands used by those commands, that is, commands that are intended foruse by other commands and not directly by a user. Furthermore, it contains kernel modules,which could be argued to be located in /opt, so do not be surpriced if you find them there oneday, but fore the time being, they are considered libraries rather than add-ons.

On x86 64 systems you will find /lib64 which points to /lib. As /lib is architecturedependent it makes no sinces to create a seperate directory for that architecture, therefore/lib64 is created to link to /lib so programs do not install them to any other directory than/lib.

6.4 /opt

/opt (from ‘optional’) is a directory of large self-contained packages, that contains their ownlibrary copies; problematic packages, that do not comform to a standard filesystem hierarchy orneed their of library copies for compatiblity reasons; application add-ons; and compat versionsof packages, that is, another version (version number) of a that is installed side by side with themane verison.

Chapter 7: Secondary hierarchy 9

7 Secondary hierarchy

7.1 /usr

/usr (“user”) is the root for the secondary hierarchy in the filesystem hierarchy. Its purpose iscontain programs that is normally not required for maintenance and system rescue.

7.2 /usr/bin

/usr/bin is the secondary hierarchy correspondence to the primary hierarchy’s /bin.

7.3 /usr/sbin

/usr/sbin is the secondary hierarchy correspondence to the primary hierarchy’s /sbin.

7.4 /usr/games

/usr/games is a historical directory whose purpose was to contain games as they normallyare much larger than other programs. It lets your store games on a different hard drive thenprograms /usr itself, which is where it is pointing today.

If you prefer, you can separate them. Correctly written game scrolls should be installed into/usr/games rather than /usr; the definition of “game” may however not be to count on, itshould be interactive games that you play, not just amusing small programs such as ponysay

and fortune.

To compile a program to be installed to /usr/games rather than /usr, just change the“prefix” in scroll from /usr to /usr/games.

7.5 /usr/libexec

/usr/libexec is the secondary hierarchy’s directory for commands that are meant for otherprograms to execute, there is however nothing stopping you from running then directly yourself,that is just not designed for that.

7.6 /usr/lib

/usr/lib is the secondary hierarchy’s directory for non-executable library files. Libraries includefunctions that are execute by programs and cannot be used a command, the reason for this is thatlibraries are more complex, and do not only contain functions and are not treated as separatedprograms.

On x86 64 systems you will find /usr/lib64 which points to /usr/lib. As /usr/lib isarchitecture dependent it makes no sinces to create a seperate directory for that architecture,therefore /usr/lib64 is created to link to /usr/lib so programs do not install them to anyother directory than /usr/lib.

Additionally, on x86 64 systems you will also find /usr/libmulti, which on most systemsare called /usr/lib32, but we wanted the name to more precisely reflect the fact that it isused for multilibs and is not of the systems actual architecture. /usr/libmulti is the home ofsecondary hierarchy libraries used by legacy 32-bit programs running under IA-32 emulation.32-bit programs are looked amongst 64-bits in /usr/bin and /usr/sbin. There are no essentialprograms that are not 64-bit compatible and therefore there is no /libmulti.

To keep it simple /usr/lib points to /lib and escapes the secondary hierarchy.


7.7 /usr/include

While /usr/lib are binaries, /usr/include are source headers for /usr/lib libraries, they areused for programs that seek to use /usr/lib libraries and need to know the structure of thoselibraries at compile time by source and not by binary.

7.8 /usr/src

/usr/src (“source”) is the directory for source files that may be needed by another programor scroll, or by the program itself. Sources for programs installed to / and /usr fits here, /optprograms should have their source in their directory inside /opt.

On a typical system this directory will contain and only contain the kernel source.

7.9 /usr/doc

/usr/doc is the directory for non-standard documentation for program in /usr. Non-standardmeans that there is no dedicated documentation program such as info and man that is usedto open the documentation, and rather, the user much on the documentention my hand in ageneral PDF viewer, text viewer or whatever is applicable.

Packages with one documentation file my use a single file in /usr/doc named as the packageoptionally followed by a file extension, otherwise a directory named as the package must be used.

Documentation for packages installed to both / and /usr should be installed here, packagesin /opt should have here documention installed to there own directory inside /opt.

7.10 /usr/share

The /usr/share hierarchy is for all read-only architecture independent data files, which means,no executable files or libraries unless they are executable libraries intended to be used by theprogram installed with them. Programs requiring data files should have a directory named asthe program directly under /usr/share.

Any program requiring architecture dependent (not independent) data is considered prob-lematic and should be installed to /opt, if the architecture dependent is not covered for allarchitectures.

Essential programs, that is, programs installed to /, should not have data files, but if required,it should be installed to /lib rather than /usr/share or /share.

7.11 /usr/share/applications

/usr/share/applications is directory for application launchers for graphical environments.

7.12 /usr/share/changelogs

Programs may install there changelogs to /usr/share/changelogs.

7.13 /usr/share/licenses

Programs should install there licenses other legal documents to /usr/share/licenses.The scrolls used to install them should however, when possible, reuse licenses found in/usr/share/licenses/common via symbolic links.

7.14 /usr/share/misc

/usr/share/misc contains miscellaneous architecture-independent files which do not require aseparate subdirectory under /usr/share.


7.15 /usr/share/info

/usr/share/info is the directory for info manuals for programs installed under /, /usr and/opt. These are more extensive, book-like (and actual books,) manuals which can be openedwith the command info. It is common practice for GNU ponies to create extensive info

manuals.

7.16 /usr/share/man

/usr/share/man is the directory for man manuals for programs installed under /, /usr and /opt.These are (almost always) short, reference card-like, manuals which can be opened with thecommand man. It is common practice for Linux ponies to create show man manuals, sometimeshowever they are really long.

7.17 /usr/share/dict

/usr/share/dict is a directory for word lists, these lists are simple text files with one word perline and are program independent.

Chapter 8: Tertiary hierarchy 12

8 Tertiary hierarchy

/usr/local is the tertiary hierarchy1, and is identical to the secondary hierarchy2, except/usr/local/share/dict is not pre-created, and should only include data for /usr/local pro-grams, and not programs installed in /, /usr or /opt. However their is an additional di-rectory /usr/local/etc for system-wide host-specific configurations for programs located in/usr/local.

/usr/local is the hierarchy for host-specific data, which includes software installed from anon-standard repository. System administrators can, here, install programs built specifically forcompany or institute, programs not found in a repository3, or system-wide shorthand command.

1 Also called the local hierarchy.2 /usr is the secondary hierarchy.3 Do request a pull for its inclusion.

Chapter 9: User hierarchy 13

9 User hierarchy

9.1 ~/.config

~/.config1 is the default location for user private settings, it does however normal fallback tothe home directory, but sometimes ~/.config is not used. ~/.config may however be changeby setting the environment variable XDG CONFIG HOME accordingly.

9.2 ~/.cache

~/.cache, which can be changed with the environment variable XDG CACHE HOME, is thedefault location for user private cached files.

9.3 ~/.spool

~/.spool is the default location for user private spooled filed.

9.4 ~/.local

~/.local is the root of the user’s personal hierarchy for user installed software, it is similarto / and /usr. It contains the directories bin, sbin symlinked to bin, games, lib, libexec,libmulti on x86 64 systems, include, src, doc and share, whose purposes are the same as in/usr. Additionally it contains opt with the same purposes as /opt and etc which is a symboliclink to ~/.config. Further it includes var with the directories games, lib, lock, log, spooland cache, whose purposes are the same as in /var

1 .config in the user’s home directory

Chapter 10: Simplified hierarchy 14

10 Simplified hierarchy

The simplified hierarchy is an optional extension to the filesystem hierarchy, that is not rec-ommended. The simplified hierarchy has symlinks to essentially all standard locations in thefilesystem hierarchy but uses simpler names, because of the only major difference is names andthat essentially only power usets actually uses the hierarchy it is recommand to just learn thenormal hierarchy which is easier to use when you know it. However the simplified hierarchyranges directories my similarity rather than have a rather flat hierarchy duplicated in threelayered groups.

10.1 /localhost

/localhost is the root of the simplified hierarchy, the standard hierarchy can be hidden in mostfile managers by installing yet another extension.

10.2 /localhost/users

Data that is meant to be used by the users are located in /localhost/users./localhost/users/private contains user homes, while /localhost/users/public containsthe directories shared, administrated and mounted which are accessable by all users.

shared contains data contributed by all users, which administrated requires privileges tomodify which by default means only root.

/media as a superdirectory of long term mount points, more specifically, it is intended toonly contain directories that are used as mount points for long term mounted filesystems thatis not incorporated into the remaining part of the filesystem hierarchy.

10.3 /localhost/temporary

/localhost/temporary contains directories for temporary data. It contains the subdirectories:

persistent

Temporary files that are perserved between boots.

transient

Temporary files that are lost between boots.

shared Files stored using the shared memory module.

cache Cached files, these can be clean at any time.

spool Spool files, these can only safely be removed by the program that added them.

large Variable data for programs in /localhost/applications/large, this does not nec-essarily contain only temporary files. It contains a directories for programs, and theprogram choose how that want to organise there variable files.

host/cache

Cached files for programs in /localhost/host/applications, these can be cleanat any time.

host/spool

Spool files for programs in /localhost/host/applications, these can only safelybe removed by the program that added them.

mount Directory file a temporarly mounted, by the user, storage device.


10.4 /localhost/applications

/localhost/applications is the location for non-essential programs. It contains the subdirec-tories:

commands This directory contains commands for non-essential programs.

games If the true filesystem hierarchy contains a separate directory for games, this directorywill exists, and contain directories such as bin for commands, and share for data.

large This directory contains large self-contained packages, that contains their own librarycopies; problematic packages, that do not comform to a standard filesystem hier-archy or need their of library copies for compatiblity reasons; application add-ons;and compat versions of packages, that is, another version (version number) of a thatis installed side by side with the mane verison.

documentations

Programs containing documentation in non-dedicated formats should install theirsuch documentation to this directory.

licenses Programs should install licenses and other legal documents to this directory.

changelogs

Programs can install change logs to this directory.

10.5 /localhost/system

/localhost/system is the location system files. It contains the subdirectories:

boot This is the mount point for the partition that the bootmanager starts and containsthe bootloader that boots an operativing system.

It contains all bootable kernels and initramfs:es that are not booted by a chainloadedbootloaders; it also contains settings for your bootloader and tools your can run,instead of your operativing system, for diagnositics.

kernel/devices

This is a mount point for the kernel advanced programming interface filesystem fordevices and pseudodevices.

kernel/processes

This is a mount point for the kernel advanced programming interface filesystem forinformation about processes. It does contain some miscellany, but it also cotainsone directory for each process named as the process ID.

kernel/access

This is a mount point for the kernel advanced programming interface filesystem forkernel and hardware access and modification.

kernel/state

This is a mount point for the advanced programming interface filesystem for run-time variable data. It contains system information describing the system since it wasbooted. Programs may have subdirectories; process identifiers and UNIX-domainsockets used by programs should be placed in this file system.

admininstrator

This is the home directory for the system administrator, the user root. Normallythere is no much point to have a home directory for the system administrator as thatis not any user intended for use beyond administrations. However, it will contianapplication configurations if the user chooses to have any, and can also be used to


store files needed for administration, that you do not want to be clutter up yournon-root user home directory.

logs This directory contains system logs.

source This is the directory for source files that may be needed by another program orscroll, or by the program itself. On a typical system this directory will contain andonly contain the kernel source.

empty This is a directory that should be empty, that services can chroot instances into tohide the file system.

resources

This directory is the root of the hierarchy for all read-only architecture independentdata files, which means, no executable files or libraries unless they are executablelibraries intended to be used by the program installed with them.

runtime/locks

This is the directory of file locks.

runtime/state

This is the directory of program and system state data.

10.6 /localhost/system/essentials

/localhost/system/essentials is the directory for essential applications. It contains thefollowing subdirectories:

maintenance

This is the directory for commands needed for system maintenance. This doesinclude command you will use regulary everyday, but not all of them, just the onesyou would also need for normal system maintenance and rescue.

system This is the directory for essential binaries used system modifications and interac-tion. While maintenance contains normal everyday commands, system containscommands normally used by the system initialisation, but primarly system dae-mons, commands for hardware and system setup, and similar commands, take apeek in for a better understanding.

libraries

This is the directory for libraries used by commands in maintenance and system,but is also contains executable non-commands used by those commands, that is,commands that are intended for use by other commands and not directly by a user.

On x86 64 systems you will find libraries64 if the real directory is not the sameas the real directory for libraries.

10.7 /localhost/system/applications

/localhost/system/essentials is the directory for non-essential applications. It contains thefollowing subdirectories:

commands This directory contains commands for non-essential programs.

system This is the directory for non-essential binaries used system modifications and inter-action.

libraries

This is the directory for libraries used by commands in commands and system.



Additionally, on x86 64 systems you will also find multilibraries, it is the homeof secondary hierarchy libraries used by legacy 32-bit programs running under IA-32emulation.

execlibraries

This is the directory for commands that are meant for other programs to execute,there is however nothing stopping you from running then directly yourself, that isjust not designed for that.

headers While libraries are binaries, headers are source headers for libraries libraries,they are used for programs that seek to use libraries libraries and need to knowthe structure of those libraries at compile time by source and not by binary.

mail This is the directory of user e-mail fetched by a e-mail service.

games This is the directory of variable game data, such as high scores.

10.8 /localhost/host

/localhost/host is the superdirectory for host-specific files, it contains the directory service

for files hosted by services provided by the host, configurations/system for system-wide con-figurations, configurations/local for system-wide configurations for host-specific programs,and configurations/large for system-wide configurations for self-contained programs.

Further it contains the directory applications with the subdirectories:

commands Host-specific commands.

games If the true filesystem hierarchy contains a separate directory for host-specific games,this directory will exists, and contain directories such as bin for commands, andshare for data.

documentation

Documentation for host-specific packages, in a non-dedicated documentation format.

licenses Licensing information for host-specific packages.

changelogs

Change logs for host-specific packages.

10.9 /localhost/host/system

/localhost/host/system contains system files that are host-specific, it contains the directories:

commands This is the directory for host-specific binaries used system modifications and inter-action.

libraries

This is the directory for libraries used only by host-specific programs.


Additionally, on x86 64 systems you will also find multilibraries, it is the homeof local hierarchy libraries used by legacy 32-bit programs running under IA-32emulation.

execlibraries

This is the directory for commands that are meant for other programs to execute,there is however nothing stopping you from running then directly yourself, that isjust not designed for that.


headers While libraries are binaries, headers are source headers for libraries libraries,they are used for programs that seek to use libraries libraries and need to knowthe structure of those libraries at compile time by source and not by binary.

source This is the directory for source files that may be needed by another program orscroll, or by the program itself.

resources

This directory is the root of the hierarchy for all read-only architecture independentdata files, which means, no executable files or libraries unless they are executablelibraries intended to be used by the program installed with them.

games This is the directory of variable game data, such as high scores.

runtime/locks

This is the directory of file locks.

runtime/state

This is the directory of program and system state data.

Chapter 11: Further simplified hierarchy 19

11 Further simplified hierarchy

If you are installing the system for a non-poweruser you may consider using the most simplifiedfilesystem hierarchy, which is limited only to the essentials.

With this extension, you get the directories /Applications, /Users, /Volumes, /Temporaryand /Shared Files. /Applications is a link to /usr/share/applications which is whereapplication lauchers are installed; /Users is a link to /home, the users’ home directories (exclud-ing root and any user with a non-standard home directory location); and /Volumes is a link to/media, the directory where hard drives and other storage devices are normally mounted.

If the true filesystem hierarchy has /shared, a directory for user shared and user adminis-trated data, /Shared Files will exist, linking to that directory.

The directory /Temporary contains the directories Persistent, Transient and Cache linkingto /var/tmp, /tmp and /var/cache respectively.

Appendix A: GNU Free Documentation License 20

Appendix A GNU Free Documentation License

Version 1.3, 3 November 2008

Copyright c© 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.http://fsf.org/

Everyone is permitted to copy and distribute verbatim copiesof this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other functional and usefuldocument free in the sense of freedom: to assure everyone the effective freedom to copyand redistribute it, with or without modifying it, either commercially or noncommercially.Secondarily, this License preserves for the author and publisher a way to get credit for theirwork, while not being considered responsible for modifications made by others.

This License is a kind of “copyleft”, which means that derivative works of the documentmust themselves be free in the same sense. It complements the GNU General Public License,which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because freesoftware needs free documentation: a free program should come with manuals providing thesame freedoms that the software does. But this License is not limited to software manuals;it can be used for any textual work, regardless of subject matter or whether it is publishedas a printed book. We recommend this License principally for works whose purpose isinstruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that contains a noticeplaced by the copyright holder saying it can be distributed under the terms of this License.Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use thatwork under the conditions stated herein. The “Document”, below, refers to any such manualor work. Any member of the public is a licensee, and is addressed as “you”. You acceptthe license if you copy, modify or distribute the work in a way requiring permission undercopyright law.

A “Modified Version” of the Document means any work containing the Document or aportion of it, either copied verbatim, or with modifications and/or translated into anotherlanguage.

A “Secondary Section” is a named appendix or a front-matter section of the Documentthat deals exclusively with the relationship of the publishers or authors of the Documentto the Document’s overall subject (or to related matters) and contains nothing that couldfall directly within that overall subject. (Thus, if the Document is in part a textbook ofmathematics, a Secondary Section may not explain any mathematics.) The relationshipcould be a matter of historical connection with the subject or with related matters, or oflegal, commercial, philosophical, ethical or political position regarding them.

The “Invariant Sections” are certain Secondary Sections whose titles are designated, asbeing those of Invariant Sections, in the notice that says that the Document is releasedunder this License. If a section does not fit the above definition of Secondary then it is notallowed to be designated as Invariant. The Document may contain zero Invariant Sections.If the Document does not identify any Invariant Sections then there are none.

The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts orBack-Cover Texts, in the notice that says that the Document is released under this License.A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25words.

http://fsf.org/


A “Transparent” copy of the Document means a machine-readable copy, represented in aformat whose specification is available to the general public, that is suitable for revisingthe document straightforwardly with generic text editors or (for images composed of pixels)generic paint programs or (for drawings) some widely available drawing editor, and that issuitable for input to text formatters or for automatic translation to a variety of formatssuitable for input to text formatters. A copy made in an otherwise Transparent file formatwhose markup, or absence of markup, has been arranged to thwart or discourage subsequentmodification by readers is not Transparent. An image format is not Transparent if used forany substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

Examples of suitable formats for Transparent copies include plain ASCII without markup,Texinfo input format, LaTEX input format, SGML or XML using a publicly available DTD,and standard-conforming simple HTML, PostScript or PDF designed for human modifica-tion. Examples of transparent image formats include PNG, XCF and JPG. Opaque formatsinclude proprietary formats that can be read and edited only by proprietary word proces-sors, SGML or XML for which the DTD and/or processing tools are not generally available,and the machine-generated HTML, PostScript or PDF produced by some word processorsfor output purposes only.

The “Title Page” means, for a printed book, the title page itself, plus such following pagesas are needed to hold, legibly, the material this License requires to appear in the title page.For works in formats which do not have any title page as such, “Title Page” means thetext near the most prominent appearance of the work’s title, preceding the beginning of thebody of the text.

The “publisher” means any person or entity that distributes copies of the Document to thepublic.

A section “Entitled XYZ” means a named subunit of the Document whose title eitheris precisely XYZ or contains XYZ in parentheses following text that translates XYZ inanother language. (Here XYZ stands for a specific section name mentioned below, suchas “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve theTitle” of such a section when you modify the Document means that it remains a section“Entitled XYZ” according to this definition.

The Document may include Warranty Disclaimers next to the notice which states thatthis License applies to the Document. These Warranty Disclaimers are considered to beincluded by reference in this License, but only as regards disclaiming warranties: any otherimplication that these Warranty Disclaimers may have is void and has no effect on themeaning of this License.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncom-mercially, provided that this License, the copyright notices, and the license notice sayingthis License applies to the Document are reproduced in all copies, and that you add noother conditions whatsoever to those of this License. You may not use technical measuresto obstruct or control the reading or further copying of the copies you make or distribute.However, you may accept compensation in exchange for copies. If you distribute a largeenough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publiclydisplay copies.

3. COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have printed covers) of theDocument, numbering more than 100, and the Document’s license notice requires CoverTexts, you must enclose the copies in covers that carry, clearly and legibly, all these CoverTexts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both


covers must also clearly and legibly identify you as the publisher of these copies. The frontcover must present the full title with all words of the title equally prominent and visible.You may add other material on the covers in addition. Copying with changes limited tothe covers, as long as they preserve the title of the Document and satisfy these conditions,can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put thefirst ones listed (as many as fit reasonably) on the actual cover, and continue the rest ontoadjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, youmust either include a machine-readable Transparent copy along with each Opaque copy,or state in or with each Opaque copy a computer-network location from which the generalnetwork-using public has access to download using public-standard network protocols acomplete Transparent copy of the Document, free of added material. If you use the latteroption, you must take reasonably prudent steps, when you begin distribution of Opaquecopies in quantity, to ensure that this Transparent copy will remain thus accessible at thestated location until at least one year after the last time you distribute an Opaque copy(directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well beforeredistributing any large number of copies, to give them a chance to provide you with anupdated version of the Document.

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditionsof sections 2 and 3 above, provided that you release the Modified Version under preciselythis License, with the Modified Version filling the role of the Document, thus licensingdistribution and modification of the Modified Version to whoever possesses a copy of it. Inaddition, you must do these things in the Modified Version:

A. Use in the Title Page (and on the covers, if any) a title distinct from that of theDocument, and from those of previous versions (which should, if there were any, belisted in the History section of the Document). You may use the same title as a previousversion if the original publisher of that version gives permission.

B. List on the Title Page, as authors, one or more persons or entities responsible forauthorship of the modifications in the Modified Version, together with at least five ofthe principal authors of the Document (all of its principal authors, if it has fewer thanfive), unless they release you from this requirement.

C. State on the Title page the name of the publisher of the Modified Version, as thepublisher.

D. Preserve all the copyright notices of the Document.

E. Add an appropriate copyright notice for your modifications adjacent to the other copy-right notices.

F. Include, immediately after the copyright notices, a license notice giving the publicpermission to use the Modified Version under the terms of this License, in the formshown in the Addendum below.

G. Preserve in that license notice the full lists of Invariant Sections and required CoverTexts given in the Document’s license notice.

H. Include an unaltered copy of this License.

I. Preserve the section Entitled “History”, Preserve its Title, and add to it an item statingat least the title, year, new authors, and publisher of the Modified Version as givenon the Title Page. If there is no section Entitled “History” in the Document, createone stating the title, year, authors, and publisher of the Document as given on its


Title Page, then add an item describing the Modified Version as stated in the previoussentence.

J. Preserve the network location, if any, given in the Document for public access to aTransparent copy of the Document, and likewise the network locations given in theDocument for previous versions it was based on. These may be placed in the “History”section. You may omit a network location for a work that was published at least fouryears before the Document itself, or if the original publisher of the version it refers togives permission.

K. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Titleof the section, and preserve in the section all the substance and tone of each of thecontributor acknowledgements and/or dedications given therein.

L. Preserve all the Invariant Sections of the Document, unaltered in their text and in theirtitles. Section numbers or the equivalent are not considered part of the section titles.

M. Delete any section Entitled “Endorsements”. Such a section may not be included inthe Modified Version.

N. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in titlewith any Invariant Section.

O. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or appendices that qualify asSecondary Sections and contain no material copied from the Document, you may at youroption designate some or all of these sections as invariant. To do this, add their titles tothe list of Invariant Sections in the Modified Version’s license notice. These titles must bedistinct from any other section titles.

You may add a section Entitled “Endorsements”, provided it contains nothing but endorse-ments of your Modified Version by various parties—for example, statements of peer reviewor that the text has been approved by an organization as the authoritative definition of astandard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of upto 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the ModifiedVersion. Only one passage of Front-Cover Text and one of Back-Cover Text may be addedby (or through arrangements made by) any one entity. If the Document already includesa cover text for the same cover, previously added by you or by arrangement made by thesame entity you are acting on behalf of, you may not add another; but you may replace theold one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission touse their names for publicity for or to assert or imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, underthe terms defined in section 4 above for modified versions, provided that you include in thecombination all of the Invariant Sections of all of the original documents, unmodified, andlist them all as Invariant Sections of your combined work in its license notice, and that youpreserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identicalInvariant Sections may be replaced with a single copy. If there are multiple InvariantSections with the same name but different contents, make the title of each such sectionunique by adding at the end of it, in parentheses, the name of the original author orpublisher of that section if known, or else a unique number. Make the same adjustment tothe section titles in the list of Invariant Sections in the license notice of the combined work.


In the combination, you must combine any sections Entitled “History” in the various originaldocuments, forming one section Entitled “History”; likewise combine any sections Entitled“Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sectionsEntitled “Endorsements.”

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released underthis License, and replace the individual copies of this License in the various documents witha single copy that is included in the collection, provided that you follow the rules of thisLicense for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individuallyunder this License, provided you insert a copy of this License into the extracted document,and follow this License in all other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independentdocuments or works, in or on a volume of a storage or distribution medium, is called an“aggregate” if the copyright resulting from the compilation is not used to limit the legalrights of the compilation’s users beyond what the individual works permit. When theDocument is included in an aggregate, this License does not apply to the other works inthe aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document,then if the Document is less than one half of the entire aggregate, the Document’s CoverTexts may be placed on covers that bracket the Document within the aggregate, or theelectronic equivalent of covers if the Document is in electronic form. Otherwise they mustappear on printed covers that bracket the whole aggregate.

8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of theDocument under the terms of section 4. Replacing Invariant Sections with translationsrequires special permission from their copyright holders, but you may include translationsof some or all Invariant Sections in addition to the original versions of these InvariantSections. You may include a translation of this License, and all the license notices inthe Document, and any Warranty Disclaimers, provided that you also include the originalEnglish version of this License and the original versions of those notices and disclaimers. Incase of a disagreement between the translation and the original version of this License or anotice or disclaimer, the original version will prevail.

If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”,the requirement (section 4) to Preserve its Title (section 1) will typically require changingthe actual title.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly pro-vided under this License. Any attempt otherwise to copy, modify, sublicense, or distributeit is void, and will automatically terminate your rights under this License.

However, if you cease all violation of this License, then your license from a particular copy-right holder is reinstated (a) provisionally, unless and until the copyright holder explicitlyand finally terminates your license, and (b) permanently, if the copyright holder fails tonotify you of the violation by some reasonable means prior to 60 days after the cessation.

Moreover, your license from a particular copyright holder is reinstated permanently if thecopyright holder notifies you of the violation by some reasonable means, this is the firsttime you have received notice of violation of this License (for any work) from that copyrightholder, and you cure the violation prior to 30 days after your receipt of the notice.


Termination of your rights under this section does not terminate the licenses of partieswho have received copies or rights from you under this License. If your rights have beenterminated and not permanently reinstated, receipt of a copy of some or all of the samematerial does not give you any rights to use it.

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Doc-umentation License from time to time. Such new versions will be similar in spirit to thepresent version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Documentspecifies that a particular numbered version of this License “or any later version” appliesto it, you have the option of following the terms and conditions either of that specifiedversion or of any later version that has been published (not as a draft) by the Free SoftwareFoundation. If the Document does not specify a version number of this License, you maychoose any version ever published (not as a draft) by the Free Software Foundation. If theDocument specifies that a proxy can decide which future versions of this License can beused, that proxy’s public statement of acceptance of a version permanently authorizes youto choose that version for the Document.

11. RELICENSING

“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Webserver that publishes copyrightable works and also provides prominent facilities for anybodyto edit those works. A public wiki that anybody can edit is an example of such a server. A“Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set ofcopyrightable works thus published on the MMC site.

“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license publishedby Creative Commons Corporation, a not-for-profit corporation with a principal place ofbusiness in San Francisco, California, as well as future copyleft versions of that licensepublished by that same organization.

“Incorporate” means to publish or republish a Document, in whole or in part, as part ofanother Document.

An MMC is “eligible for relicensing” if it is licensed under this License, and if all works thatwere first published under this License somewhere other than this MMC, and subsequentlyincorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections,and (2) were thus incorporated prior to November 1, 2008.

The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible forrelicensing.

http://www.gnu.org/copyleft/

http://www.gnu.org/copyleft/


ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the documentand put the following copyright and license notices just after the title page:

Copyright (C) year your name.

Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.3

or any later version published by the Free Software Foundation;

with no Invariant Sections, no Front-Cover Texts, and no Back-Cover

Texts. A copy of the license is included in the section entitled ‘‘GNU

Free Documentation License’’.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the“with. . .Texts.” line with this:

with the Invariant Sections being list their titles, with

the Front-Cover Texts being list, and with the Back-Cover Texts

being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three,merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasingthese examples in parallel under your choice of free software license, such as the GNU GeneralPublic License, to permit their use in free software.