add specification for XDG_RUNTIME_DIR

1 files changed, 103 insertions, 35 deletions

diff --git a/basedir/basedir-spec.xml b/basedir/basedir-spec.xml
index fa8d2ba..b3c4fa2 100644
--- a/basedir/basedir-spec.xml
+++ b/basedir/basedir-spec.xml
@@ -4,8 +4,8 @@
 <article id="index">
   <articleinfo>
     <title>XDG Base Directory Specification</title>
-    <releaseinfo>Version 0.6</releaseinfo>
-    <date>31 July 2003</date>
+    <releaseinfo>Version 0.7</releaseinfo>
+    <date>24th November 2010</date>
     <authorgroup>
       <author>
 	<firstname>Waldo</firstname>
@@ -16,23 +16,41 @@
 	  </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. 
+      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: 
+      The XDG Base Directory Specification is based on the following concepts:
       <itemizedlist>
         <listitem>
           <para>
@@ -58,7 +76,7 @@
         <listitem>
           <para>
             There is a set of preference ordered base directories relative to
-            which configuration files should be searched.  
+            which configuration files should be searched.
             This set of directories is defined
             by the environment variable <literal>$XDG_CONFIG_DIRS</literal>.
           </para>
@@ -66,11 +84,20 @@
         <listitem>
           <para>
             There is a single base directory relative to which user-specific
-            non-essential (cached) data should be written. 
+            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 non-essential 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>
   </sect1>
@@ -92,32 +119,32 @@
     </para>
     <para>
       <literal>$XDG_DATA_DIRS</literal> defines the preference-ordered set of
-      base directories to search for data files in addition to the 
+      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 
+      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. 
+      /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 
+      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 
+      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. 
+      /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 
+      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
@@ -129,6 +156,48 @@
       <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">
@@ -155,9 +224,9 @@
         <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 
+            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>
@@ -185,37 +254,37 @@
         <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 
+            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 
+      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 
+      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, 
+      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 
+      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 
+      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.
@@ -223,4 +292,3 @@
   </sect1>
 
 </article>
-