basedir-spec-latest.html

<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>XDG Base Directory Specification</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"><div class="titlepage"><div><div><h2 class="title"><a name="index"></a>XDG Base Directory Specification</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Waldo</span> <span class="surname">Bastian</span></h3><div class="affiliation"><div class="address"><p><br>
            <code class="email">&lt;<a class="email" href="mailto:bastian@kde.org">bastian@kde.org</a>&gt;</code><br>
          </p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Allison</span> <span class="surname">Karlitskaya</span></h3><div class="affiliation"><div class="address"><p><br>
            <code class="email">&lt;<a class="email" href="mailto:desrt@desrt.ca">desrt@desrt.ca</a>&gt;</code><br>
          </p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Lennart</span> <span class="surname">Poettering</span></h3><div class="affiliation"><div class="address"><p><br>
            <code class="email">&lt;<a class="email" href="mailto:lennart@poettering.net">lennart@poettering.net</a>&gt;</code><br>
          </p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Johannes</span> <span class="surname">Löthberg</span></h3><div class="affiliation"><div class="address"><p><br>
            <code class="email">&lt;<a class="email" href="mailto:johannes@kyriasis.com">johannes@kyriasis.com</a>&gt;</code><br>
          </p></div></div></div></div></div><div><p class="releaseinfo">Version 0.8</p></div><div><p class="pubdate">08th May 2021</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="#introduction">Introduction</a></span></dt><dt><span class="sect1"><a href="#basics">Basics</a></span></dt><dt><span class="sect1"><a href="#variables">Environment variables</a></span></dt><dt><span class="sect1"><a href="#referencing">Referencing this specification</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction</h2></div></div></div><p>
      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.
    </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="basics"></a>Basics</h2></div></div></div><p>
      The XDG Base Directory Specification is based on the following concepts:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            There is a single base directory relative to which user-specific
            data files should be written. This directory is defined by the
            environment variable <code class="literal">$XDG_DATA_HOME</code>.
          </p></li><li class="listitem"><p>
            There is a single base directory relative to which user-specific
            configuration files should be written. This directory is defined by the
            environment variable <code class="literal">$XDG_CONFIG_HOME</code>.
          </p></li><li class="listitem"><p>
            There is a single base directory relative to which user-specific
            state data should be written. This directory is defined by the
            environment variable <code class="literal">$XDG_STATE_HOME</code>.
          </p></li><li class="listitem"><p>
            There is a single base directory relative to which
            user-specific executable files may be written.
          </p></li><li class="listitem"><p>
            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 <code class="literal">$XDG_DATA_DIRS</code>.
          </p></li><li class="listitem"><p>
            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 <code class="literal">$XDG_CONFIG_DIRS</code>.
          </p></li><li class="listitem"><p>
            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 <code class="literal">$XDG_CACHE_HOME</code>.
          </p></li><li class="listitem"><p>
            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 <code class="literal">$XDG_RUNTIME_DIR</code>.
          </p></li></ul></div><p>
    </p><p>
      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.
    </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="variables"></a>Environment variables</h2></div></div></div><p>
      <code class="literal">$XDG_DATA_HOME</code> defines the base directory relative to
      which user-specific data files should be stored. If
      <code class="literal">$XDG_DATA_HOME</code> is either not set or empty, a default equal to
      <code class="literal">$HOME</code>/.local/share should be used.
    </p><p>
      <code class="literal">$XDG_CONFIG_HOME</code> defines the base directory relative to
      which user-specific configuration files should be stored. If
      <code class="literal">$XDG_CONFIG_HOME</code> is either not set or empty, a default equal to
      <code class="literal">$HOME</code>/.config should be used.
    </p><p>
      <code class="literal">$XDG_STATE_HOME</code> defines the base directory relative to
      which user-specific state files should be stored. If
      <code class="literal">$XDG_STATE_HOME</code> is either not set or empty, a default equal to
      <code class="literal">$HOME</code>/.local/state should be used.
    </p><p>
      The <code class="literal">$XDG_STATE_HOME</code> contains state data that should persist between
      (application) restarts, but that is not important or portable enough to the user that it should be stored
      in <code class="literal">$XDG_DATA_HOME</code>. It may contain:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>actions history (logs, history, recently used files, …)</p></li><li class="listitem"><p>current state of the application that can be reused on a restart (view, layout,
        open files, undo history, …)</p></li></ul></div><p>
    </p><p>
      User-specific executable files may be stored in
      <code class="literal">$HOME</code>/.local/bin. Distributions should ensure
      this directory shows up in the UNIX <code class="literal">$PATH</code>
      environment variable, at an appropriate place.
    </p><p>
      Since <code class="literal">$HOME</code> might be shared between systems
      of different achitectures, installing compiled binaries to
      <code class="literal">$HOME</code>/.local/bin could cause
      problems when used on systems of differing architectures. This
      is often not a problem, but the fact that
      <code class="literal">$HOME</code> becomes partially achitecture-specific
      if compiled binaries are placed in it should be kept in mind.
    </p><p>
      <code class="literal">$XDG_DATA_DIRS</code> defines the preference-ordered set of
      base directories to search for data files in addition to the
      <code class="literal">$XDG_DATA_HOME</code> base directory.
      The directories in <code class="literal">$XDG_DATA_DIRS</code> should be seperated
      with a colon ':'.
    </p><p>
      If <code class="literal">$XDG_DATA_DIRS</code> is either not set or empty, a value equal to
      /usr/local/share/:/usr/share/ should be used.
    </p><p>
      <code class="literal">$XDG_CONFIG_DIRS</code> defines the preference-ordered set of
      base directories to search for configuration files in addition to the
      <code class="literal">$XDG_CONFIG_HOME</code> base directory.
      The directories in <code class="literal">$XDG_CONFIG_DIRS</code> should be seperated
      with a colon ':'.
    </p><p>
      If <code class="literal">$XDG_CONFIG_DIRS</code> is either not set or empty, a value equal to
      /etc/xdg should be used.
    </p><p>
      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 <code class="literal">$XDG_DATA_HOME</code> is considered more important than
      any of the base directories defined by <code class="literal">$XDG_DATA_DIRS</code>.
      The base directory defined
      by <code class="literal">$XDG_CONFIG_HOME</code> is considered more important than
      any of the base directories defined by <code class="literal">$XDG_CONFIG_DIRS</code>.
    </p><p>
      <code class="literal">$XDG_CACHE_HOME</code> defines the base directory relative to
      which user-specific non-essential data files should be stored. If
      <code class="literal">$XDG_CACHE_HOME</code> is either not set or empty, a default equal to
      <code class="literal">$HOME</code>/.cache should be used.
    </p><p>
      <code class="literal">$XDG_RUNTIME_DIR</code> 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.
    </p><p>
      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.
    </p><p>
      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.
    </p><p>
      If <code class="literal">$XDG_RUNTIME_DIR</code> 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.
    </p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="referencing"></a>Referencing this specification</h2></div></div></div><p>
      Other specifications may reference this specification by specifying the
      location of a data file as
      <code class="literal">$XDG_DATA_DIRS</code>/subdir/filename. This implies that:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Such file should be installed to <code class="literal">$datadir</code>/subdir/filename
            with <code class="literal">$datadir</code> defaulting to /usr/share.
          </p></li><li class="listitem"><p>
            A user-specific version of the data file may be created in
            <code class="literal">$XDG_DATA_HOME</code>/subdir/filename, taking into
            account the default value for <code class="literal">$XDG_DATA_HOME</code> if
            <code class="literal">$XDG_DATA_HOME</code> is not set.
          </p></li><li class="listitem"><p>
            Lookups of the data file should search for ./subdir/filename relative to
            all base directories specified by <code class="literal">$XDG_DATA_HOME</code> and
            <code class="literal">$XDG_DATA_DIRS</code> . If an environment
            variable is either not set or empty, its default value as defined by this specification
            should be used instead.
          </p></li></ul></div><p>
    </p><p>
      Specifications may reference this specification by specifying the
      location of a configuration file as
      <code class="literal">$XDG_CONFIG_DIRS</code>/subdir/filename. This implies that:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Default configuration files should be installed to <code class="literal">$sysconfdir</code>/xdg/subdir/filename
            with <code class="literal">$sysconfdir</code> defaulting to /etc.
          </p></li><li class="listitem"><p>
            A user-specific version of the configuration file may be created in
            <code class="literal">$XDG_CONFIG_HOME</code>/subdir/filename, taking into
            account the default value for <code class="literal">$XDG_CONFIG_HOME</code> if
            <code class="literal">$XDG_CONFIG_HOME</code> is not set.
          </p></li><li class="listitem"><p>
            Lookups of the configuration file should search for ./subdir/filename relative to
            all base directories indicated by <code class="literal">$XDG_CONFIG_HOME</code> and
            <code class="literal">$XDG_CONFIG_DIRS</code> . If an environment
            variable is either not set or empty, its default value as defined by this specification
            should be used instead.
          </p></li></ul></div><p>
    </p><p>
      If, when attempting to write a file, the destination
      directory is non-existent an attempt should be made to create it
      with permission <code class="literal">0700</code>. 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-existent
      and could not be created, or for any other reason. In such case it
      may choose to present an error message to the user.
    </p><p>
      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-existent,
      the file is non-existent 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 choose to present an error message to the user.
    </p><p>
      A specification that refers to <code class="literal">$XDG_DATA_DIRS</code> or
      <code class="literal">$XDG_CONFIG_DIRS</code> 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.
    </p></div></div></body></html>