Merging upstream version 256.1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

2 files changed, 49 insertions, 30 deletions

diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml
index 008bff6..2a494b9 100644
--- a/man/systemd-tmpfiles.xml
+++ b/man/systemd-tmpfiles.xml
@@ -55,9 +55,11 @@
   <refsect1>
     <title>Description</title>
 
-    <para><command>systemd-tmpfiles</command> creates, deletes, and cleans up volatile and temporary files
-    and directories, using the configuration file format and location specified in
-    <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. It must
+    <para><command>systemd-tmpfiles</command> creates, deletes, and cleans up files and directories, using
+    the configuration file format and location specified in
+    <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    Historically, it was designed to manage volatile and temporary files, as the name suggests, but it provides
+    generic file management functionality and can be used to manage any kind of files. It must
     be invoked with one or more commands <option>--create</option>, <option>--remove</option>, and
     <option>--clean</option>, to select the respective subset of operations.</para>
 
@@ -149,8 +151,26 @@
 
       <varlistentry>
         <term><option>--purge</option></term>
-        <listitem><para>If this option is passed, all files and directories created by a
-        <filename>tmpfiles.d/</filename> entry will be deleted.</para>
+
+        <listitem><para>If this option is passed, all files and directories marked for
+        <emphasis>creation</emphasis> by the <filename>tmpfiles.d/</filename> files specified on the command
+        line will be <emphasis>deleted</emphasis>. Specifically, this acts on all files and directories
+        marked with <varname>f</varname>, <varname>F</varname>, <varname>d</varname>, <varname>D</varname>,
+        <varname>v</varname>, <varname>q</varname>, <varname>Q</varname>, <varname>p</varname>,
+        <varname>L</varname>, <varname>c</varname>, <varname>b</varname>, <varname>C</varname>,
+        <varname>w</varname>, <varname>e</varname>. If this switch is used at least one
+        <filename>tmpfiles.d/</filename> file (or <filename>-</filename> for standard input) must be
+        specified on the command line or the invocation will be refused, for safety reasons (as otherwise
+        much of the installed system files might be removed).</para>
+
+        <para>The primary usecase for this option is to automatically remove files and directories that
+        originally have been created on behalf of an installed packaged at package removal time.</para>
+
+        <para>It is recommended to first run this command in combination with <option>--dry-run</option>
+        (see below) to verify which files and directories will be deleted.</para>
+
+        <para><emphasis>Warning!</emphasis> This is is usually not the command you want! In most cases
+        <option>--remove</option> is what you are looking for.</para>
 
         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
       </varlistentry>
diff --git a/man/systemd.xml b/man/systemd.xml
index 66db5bb..f4aa7e0 100644
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -62,10 +62,29 @@
     <filename>user.conf.d</filename> directories. See
     <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     for more information.</para>
+
+    <para><command>systemd</command> contains native implementations of various tasks that need to be
+    executed as part of the boot process. For example, it sets the hostname or configures the loopback
+    network device. It also sets up and mounts various API file systems, such as <filename>/sys/</filename>,
+    <filename>/proc/</filename>, and <filename>/dev/</filename>.</para>
+
+    <para>Note that some but not all interfaces provided by systemd are covered by the
+    <ulink url="https://systemd.io/PORTABILITY_AND_STABILITY/">Interface Portability and Stability Promise</ulink>.</para>
+
+    <para>The D-Bus API of <command>systemd</command> is described in
+    <citerefentry><refentrytitle>org.freedesktop.systemd1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    and
+    <citerefentry><refentrytitle>org.freedesktop.LogControl1</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    </para>
+
+    <para>Systems which invoke systemd in a container or initrd environment should implement the <ulink
+    url="https://systemd.io/CONTAINER_INTERFACE">Container Interface</ulink> or
+    <ulink url="https://systemd.io/INITRD_INTERFACE/">initrd Interface</ulink>
+    specifications, respectively.</para>
   </refsect1>
 
   <refsect1>
-    <title>Concepts</title>
+    <title>Units</title>
 
     <para>systemd provides a dependency system between various
     entities called "units" of 11 different types. Units encapsulate
@@ -261,34 +280,10 @@
     example, start jobs for any of those inactive units getting queued as
     well.</para>
 
-    <para>systemd contains native implementations of various tasks
-    that need to be executed as part of the boot process. For example,
-    it sets the hostname or configures the loopback network device. It
-    also sets up and mounts various API file systems, such as
-    <filename>/sys/</filename> or <filename>/proc/</filename>.</para>
-
-    <para>For more information about the concepts and
-    ideas behind systemd, please refer to the
-    <ulink url="https://0pointer.de/blog/projects/systemd.html">Original Design Document</ulink>.</para>
-
-    <para>Note that some but not all interfaces provided by systemd are covered by the
-    <ulink url="https://systemd.io/PORTABILITY_AND_STABILITY/">Interface Portability and Stability Promise</ulink>.</para>
-
     <para>Units may be generated dynamically at boot and system
     manager reload time, for example based on other configuration
     files or parameters passed on the kernel command line. For details, see
     <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
-
-    <para>The D-Bus API of <command>systemd</command> is described in
-    <citerefentry><refentrytitle>org.freedesktop.systemd1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-    and
-    <citerefentry><refentrytitle>org.freedesktop.LogControl1</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
-    </para>
-
-    <para>Systems which invoke systemd in a container or initrd environment should implement the <ulink
-    url="https://systemd.io/CONTAINER_INTERFACE">Container Interface</ulink> or
-    <ulink url="https://systemd.io/INITRD_INTERFACE/">initrd Interface</ulink>
-    specifications, respectively.</para>
   </refsect1>
 
   <refsect1>
@@ -1558,6 +1553,10 @@
       <member><citerefentry project='man-pages'><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
     </simplelist></para>
+
+    <para>For more information about the concepts and
+    ideas behind systemd, please refer to the
+    <ulink url="https://0pointer.de/blog/projects/systemd.html">Original Design Document</ulink>.</para>
   </refsect1>
 
 </refentry>