diff options
Diffstat (limited to 'basedir/basedir-spec.xml')
| -rw-r--r-- | basedir/basedir-spec.xml | 298 |
1 files changed, 298 insertions, 0 deletions
diff --git a/basedir/basedir-spec.xml b/basedir/basedir-spec.xml new file mode 100644 index 0000000..03a982b --- /dev/null +++ b/basedir/basedir-spec.xml @@ -0,0 +1,298 @@ +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ + ]> +<article id="index"> + <articleinfo> + <title>XDG Base Directory Specification</title> + <releaseinfo>Version 0.7</releaseinfo> + <date>24th November 2010</date> + <authorgroup> + <author> + <firstname>Waldo</firstname> + <surname>Bastian</surname> + <affiliation> + <address> + <email>bastian@kde.org</email> + </address> + </affiliation> + </author> + <author> + <firstname>Ryan</firstname> + <surname>Lortie</surname> + <affiliation> + <address> + <email>desrt@desrt.ca</email> + </address> + </affiliation> + </author> + <author> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <affiliation> + <address> + <email>lennart@poettering.net</email> + </address> + </affiliation> + </author> + </authorgroup> + </articleinfo> + + <sect1 id="introduction"> + <title>Introduction</title> + <para> + Various specifications specify files and file formats. This + specification defines where these files should be looked for by + defining one or more base directories relative to which files + should be located. + </para> + </sect1> + + <sect1 id="basics"> + <title>Basics</title> + <para> + The XDG Base Directory Specification is based on the following concepts: + <itemizedlist> + <listitem> + <para> + There is a single base directory relative to which user-specific + data files should be written. This directory is defined by the + environment variable <literal>$XDG_DATA_HOME</literal>. + </para> + </listitem> + <listitem> + <para> + There is a single base directory relative to which user-specific + configuration files should be written. This directory is defined by the + environment variable <literal>$XDG_CONFIG_HOME</literal>. + </para> + </listitem> + <listitem> + <para> + There is a set of preference ordered base directories relative to + which data files should be searched. This set of directories is defined + by the environment variable <literal>$XDG_DATA_DIRS</literal>. + </para> + </listitem> + <listitem> + <para> + There is a set of preference ordered base directories relative to + which configuration files should be searched. + This set of directories is defined + by the environment variable <literal>$XDG_CONFIG_DIRS</literal>. + </para> + </listitem> + <listitem> + <para> + There is a single base directory relative to which user-specific + non-essential (cached) data should be written. + This directory is defined by the + environment variable <literal>$XDG_CACHE_HOME</literal>. + </para> + </listitem> + <listitem> + <para> + There is a single base directory relative to which + user-specific runtime files and other file objects should + be placed. This directory is defined by the environment + variable <literal>$XDG_RUNTIME_DIR</literal>. + </para> + </listitem> + </itemizedlist> + </para> + + <para>All paths set in these environment variables must be + absolute. If an implementation encounters a relative path in any + of these variables it should consider the path invalid and ignore + it.</para> + </sect1> + + + <sect1 id="variables"> + <title>Environment variables</title> + <para> + <literal>$XDG_DATA_HOME</literal> defines the base directory relative to + which user specific data files should be stored. If + <literal>$XDG_DATA_HOME</literal> is either not set or empty, a default equal to + <literal>$HOME</literal>/.local/share should be used. + </para> + <para> + <literal>$XDG_CONFIG_HOME</literal> defines the base directory relative to + which user specific configuration files should be stored. If + <literal>$XDG_CONFIG_HOME</literal> is either not set or empty, a default equal to + <literal>$HOME</literal>/.config should be used. + </para> + <para> + <literal>$XDG_DATA_DIRS</literal> defines the preference-ordered set of + base directories to search for data files in addition to the + <literal>$XDG_DATA_HOME</literal> base directory. + The directories in <literal>$XDG_DATA_DIRS</literal> should be seperated + with a colon ':'. + </para> + <para> + If <literal>$XDG_DATA_DIRS</literal> is either not set or empty, a value equal to + /usr/local/share/:/usr/share/ should be used. + </para> + <para> + <literal>$XDG_CONFIG_DIRS</literal> defines the preference-ordered set of + base directories to search for configuration files in addition to the + <literal>$XDG_CONFIG_HOME</literal> base directory. + The directories in <literal>$XDG_CONFIG_DIRS</literal> should be seperated + with a colon ':'. + </para> + <para> + If <literal>$XDG_CONFIG_DIRS</literal> is either not set or empty, a value equal to + /etc/xdg should be used. + </para> + <para> + The order of base directories denotes their importance; the first + directory listed is the most important. When the same information is + defined in multiple places the information defined relative to the more + important base directory takes precedent. The base directory defined + by <literal>$XDG_DATA_HOME</literal> is considered more important than + any of the base directories defined by <literal>$XDG_DATA_DIRS</literal>. + The base directory defined + by <literal>$XDG_CONFIG_HOME</literal> is considered more important than + any of the base directories defined by <literal>$XDG_CONFIG_DIRS</literal>. + </para> + <para> + <literal>$XDG_CACHE_HOME</literal> defines the base directory relative to + which user specific non-essential data files should be stored. If + <literal>$XDG_CACHE_HOME</literal> is either not set or empty, a default equal to + <literal>$HOME</literal>/.cache should be used. + </para> + + <para> + <literal>$XDG_RUNTIME_DIR</literal> defines the base directory + relative to which user-specific non-essential runtime files and + other file objects (such as sockets, named pipes, ...) should be + stored. The directory MUST be owned by the user, and he MUST be + the only one having read and write access to it. Its Unix access + mode MUST be 0700. + </para> + <para> + The lifetime of the directory MUST be bound to the user being + logged in. It MUST be created when the user first logs in and if + the user fully logs out the directory MUST be removed. If the + user logs in more than once he should get pointed to the same + directory, and it is mandatory that the directory continues to + exist from his first login to his last logout on the system, and + not removed in between. Files in the directory MUST not survive + reboot or a full logout/login cycle. + </para> + <para> + The directory MUST be on a local file system and not shared with + any other system. The directory MUST by fully-featured by the + standards of the operating system. More specifically, on + Unix-like operating systems AF_UNIX sockets, symbolic links, + hard links, proper permissions, file locking, sparse files, + memory mapping, file change notifications, a reliable hard link + count must be supported, and no restrictions on the file name + character set should be imposed. Files in this directory MAY be + subjected to periodic clean-up. To ensure that your files are + not removed, they should have their access time timestamp + modified at least once every 6 hours of monotonic time or the + 'sticky' bit should be set on the file. + </para> + <para> + If <literal>$XDG_RUNTIME_DIR</literal> is not set applications + should fall back to a replacement directory with similar + capabilities and print a warning message. Applications should + use this directory for communication and synchronization + purposes and should not place larger files in it, since it might + reside in runtime memory and cannot necessarily be swapped out + to disk. + </para> + </sect1> + + <sect1 id="referencing"> + <title>Referencing this specification</title> + <para> + Other specifications may reference this specification by specifying the + location of a data file as + <literal>$XDG_DATA_DIRS</literal>/subdir/filename. This implies that: + <itemizedlist> + <listitem> + <para> + Such file should be installed to <literal>$datadir</literal>/subdir/filename + with <literal>$datadir</literal> defaulting to /usr/share. + </para> + </listitem> + <listitem> + <para> + A user specific version of the data file may be created in + <literal>$XDG_DATA_HOME</literal>/subdir/filename, taking into + account the default value for <literal>$XDG_DATA_HOME</literal> if + <literal>$XDG_DATA_HOME</literal> is not set. + </para> + </listitem> + <listitem> + <para> + Lookups of the data file should search for ./subdir/filename relative to + all base directories specified by <literal>$XDG_DATA_HOME</literal> and + <literal>$XDG_DATA_DIRS</literal> . If an environment + variable is either not set or empty, its default value as defined by this specification + should be used instead. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Specifications may reference this specification by specifying the + location of a configuration file as + <literal>$XDG_CONFIG_DIRS</literal>/subdir/filename. This implies that: + <itemizedlist> + <listitem> + <para> + Default configuration files should be installed to <literal>$sysconfdir</literal>/xdg/subdir/filename + with <literal>$sysconfdir</literal> defaulting to /etc. + </para> + </listitem> + <listitem> + <para> + A user specific version of the configuration file may be created in + <literal>$XDG_CONFIG_HOME</literal>/subdir/filename, taking into + account the default value for <literal>$XDG_CONFIG_HOME</literal> if + <literal>$XDG_CONFIG_HOME</literal> is not set. + </para> + </listitem> + <listitem> + <para> + Lookups of the configuration file should search for ./subdir/filename relative to + all base directories indicated by <literal>$XDG_CONFIG_HOME</literal> and + <literal>$XDG_CONFIG_DIRS</literal> . If an environment + variable is either not set or empty, its default value as defined by this specification + should be used instead. + </para> + </listitem> + </itemizedlist> + </para> + <para> + If, when attempting to write a file, the destination + directory is non-existant an attempt should be made to create it + with permission <literal>0700</literal>. If the destination directory + exists already the permissions should not be changed. + The application should be prepared to handle the case where the file + could not be written, either because the directory was non-existant + and could not be created, or for any other reason. In such case it + may chose to present an error message to the user. + </para> + <para> + When attempting to read a file, if for any reason a file in a certain + directory is unaccessible, e.g. because the directory is non-existant, + the file is non-existant or the user is not authorized to open the file, + then the processing of the file in that directory should be skipped. + If due to this a required file could not be found at all, the + application may chose to present an error message to the user. + </para> + <para> + A specification that refers to <literal>$XDG_DATA_DIRS</literal> or + <literal>$XDG_CONFIG_DIRS</literal> should define what the behaviour + must be when a file is located under multiple base directories. + It could, for example, define that only the file under the most + important base directory should be used or, as another example, + it could define rules for merging the information from the different + files. + </para> + </sect1> + +</article> |