test-hostname-util: add assert_se's to make coverity happy

[thirdparty/systemd.git] / man / tmpfiles.d.xml

diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml
index e040a1636d20204eaa9d6bfb015ae0615977a558..793c12400717a3a328950a6e48f76635c0f5713d 100644 (file)
--- a/man/tmpfiles.d.xml
+++ b/man/tmpfiles.d.xml
@@ -1,6 +1,8 @@
 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <!--
+  SPDX-License-Identifier: LGPL-2.1+
+
   This file is part of systemd.
 
   Copyright 2010 Brandon Philips
@@ -76,7 +78,7 @@
   </refsect1>
 
   <refsect1>
-    <title>Configuration Format</title>
+    <title>Configuration Directories and Precedence</title>
 
     <para>Each configuration file shall be named in the style of
     <filename><replaceable>package</replaceable>.conf</filename> or
@@ -112,13 +114,17 @@
     to <filename>/dev/null</filename> in
     <filename>/etc/tmpfiles.d/</filename> bearing the same filename.
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Configuration File Format</title>
 
     <para>The configuration format is one line per path containing
     type, path, mode, ownership, age, and argument fields:</para>
 
     <programlisting>#Type Path        Mode UID  GID  Age Argument
-    d    /run/user   0755 root root 10d -
-    L    /tmp/foobar -    -    -    -   /dev/null</programlisting>
+d     /run/user   0755 root root 10d -
+L     /tmp/foobar -    -    -    -   /dev/null</programlisting>
 
     <para>Fields may be enclosed within quotes and contain C-style escapes.</para>
 
@@ -159,7 +165,7 @@
           <term><varname>d</varname></term>
           <listitem><para>Create a directory. The mode and ownership will be adjusted if
           specified and the directory already exists. Contents of this directory are subject
-          to time based cleanup if the time argument is specified.</para></listitem>
+          to time based cleanup if the age argument is specified.</para></listitem>
         </varlistentry>
 
         <varlistentry>
@@ -171,9 +177,13 @@
 
         <varlistentry>
           <term><varname>e</varname></term>
-          <listitem><para>Similar to <varname>d</varname>, but the directory will not be
-          created if it does not exist. Lines of this type accept shell-style globs in
-          place of normal path names.</para></listitem>
+          <listitem><para>Similar to <varname>d</varname>, but the directory will not be created if
+          it does not exist. Lines of this type accept shell-style globs in place of normal path
+          names. For this entry to be useful, at least one of the mode, uid, gid, or age arguments
+          must be specified, since otherwise this entry has no effect. If the age argument is
+          <literal>0</literal>, contents of the directory will be unconditionally deleted every time
+          <command>systemd-tmpfiles --clean</command> is run. This can be useful when combined with
+          <varname>!</varname>, see the examples.</para></listitem>
         </varlistentry>
 
         <varlistentry>
@@ -269,13 +279,14 @@
           <term><varname>L</varname></term>
           <term><varname>L+</varname></term>
           <listitem><para>Create a symlink if it does not exist
-          yet. If suffixed with <varname>+</varname> and a file
-          already exists where the symlink is to be created, it will
-          be removed and be replaced by the symlink. If the argument
-          is omitted, symlinks to files with the same name residing in
-          the directory <filename>/usr/share/factory/</filename> are
-          created. Note that permissions and ownership on symlinks
-          are ignored.</para></listitem>
+          yet. If suffixed with <varname>+</varname> and a file or
+          directory already exists where the symlink is to be created,
+          it will be removed and be replaced by the symlink. If the
+          argument is omitted, symlinks to files with the same name
+          residing in the directory
+          <filename>/usr/share/factory/</filename> are created. Note
+          that permissions and ownership on symlinks are ignored.
+          </para></listitem>
         </varlistentry>
 
         <varlistentry>
@@ -458,10 +469,10 @@
 
       <para>For example:
       <programlisting># Make sure these are created by default so that nobody else can
-      d /tmp/.X11-unix 1777 root root 10d
+d /tmp/.X11-unix 1777 root root 10d
 
-      # Unlink the X11 lock files
-      r! /tmp/.X[0-9]*-lock</programlisting>
+# Unlink the X11 lock files
+r! /tmp/.X[0-9]*-lock</programlisting>
       The second line in contrast to the first one would break a
       running system, and will only be executed with
       <option>--boot</option>.</para>
@@ -673,13 +684,25 @@ d /var/tmp/abrt 0755 abrt abrt -
 r! /var/cache/dnf/*/*/download_lock.pid
 r! /var/cache/dnf/*/*/metadata_lock.pid
 r! /var/lib/dnf/rpmdb_lock.pid
-e  /var/chache/dnf/ - - - 30d
+e  /var/cache/dnf/ - - - 30d
 </programlisting>
 
      <para>The lock files will be removed during boot. Any files and directories in
-     <filename>/var/chache/dnf/</filename> will be removed after they have not been
+     <filename>/var/cache/dnf/</filename> will be removed after they have not been
      accessed in 30 days.</para>
     </example>
+
+    <example>
+      <title>Empty the contents of a cache directory on boot</title>
+
+      <programlisting># /usr/lib/tmpfiles.d/krb5rcache.conf
+e! /var/cache/krb5rcache - - - 0
+</programlisting>
+
+      <para>Any files and subdirectories in <filename>/var/cache/krb5rcache/</filename>
+      will be removed on boot. The directory will not be created.
+      </para>
+    </example>
   </refsect1>
 
   <refsect1>