From b492568d6a2b0cda271f28bc61ebc31df8cef296 Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Wed, 19 Jun 2024 11:15:54 +0200
Subject: Adding upstream version 256.1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 man/systemd-tmpfiles.xml | 30 +++++++++++++++++++++++++-----
 1 file changed, 25 insertions(+), 5 deletions(-)

(limited to 'man/systemd-tmpfiles.xml')

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>
-- 
cgit v1.2.3