docs: properly document inhibitor locks

I still am annoyed that this wasn't documented properly when the
inhibitor locks where modified, even though raised multiple times in PR
reviews.

Follow-up for: #30307
See: #34091

diff --git a/docs/INHIBITOR_LOCKS.md b/docs/INHIBITOR_LOCKS.md
index a7e2d91fdf51fe0e860a8196c5c306e15963ef5e..fdf7b1e9ff1a4a656f4dd0cedb8224b43a7100a4 100644 (file)
--- a/docs/INHIBITOR_LOCKS.md
+++ b/docs/INHIBITOR_LOCKS.md
@@ -42,8 +42,8 @@ If such a lock is taken the operation will fail (but still may be overridden if
 The InhibitDelayMaxSec= setting in [logind.conf(5)](http://www.freedesktop.org/software/systemd/man/logind.conf.html) controls the timeout for this. This is intended to be used by applications which need a synchronous way to execute actions before system suspend but shall not be allowed to block suspend indefinitely.
 This mode is only available for _sleep_ and _shutdown_ locks.
 
-3. _block-weak_ that works as its non-weak counterpart, but that in addition may be ignored
-automatically and silently under certain circumstances, unlike the former which is always respected.
+3. _block-weak_ is identical to _block_, but has no effect on operations
+   requested by root or by the user owning the inhibitor lock.
 
 Inhibitor locks are taken via the Inhibit() D-Bus call on the logind Manager object:
 

diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml
index c344cb3014c62d7eb79968fc6e9830c1a67ddd8b..190203219546bc86745020af107fb6d0da126e19 100644 (file)
--- a/man/org.freedesktop.login1.xml
+++ b/man/org.freedesktop.login1.xml
@@ -675,16 +675,20 @@ node /org/freedesktop/login1 {
 #define SD_LOGIND_SKIP_INHIBITORS                (UINT64_C(1) << 4)
 </programlisting>
       <para>When the <varname>flags</varname> is 0 then these methods behave just like the versions without
-      flags. Since systemd version 257 active inhibitors are honoured by default for privileged users too.
-      <constant>SD_LOGIND_ROOT_CHECK_INHIBITORS</constant> (0x01) now only applies to weak inhibitors, to
-      request that they honoured for privileged users too, since they ignore them by default. A new flag
-      <constant>SD_LOGIND_SKIP_INHIBITORS</constant> (0x04) can be specified to bypass all types of
-      inhibitors. When <constant>SD_LOGIND_KEXEC_REBOOT</constant> (0x02) is set, then
-      <function>RebootWithFlags()</function> performs a kexec reboot if kexec kernel is loaded. When
-      <constant>SD_LOGIND_SOFT_REBOOT</constant> (0x04) is set, or
-      <constant>SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP</constant> (0x08) is set and a new root file system
-      has been set up on <literal>/run/nextroot/</literal>, then <function>RebootWithFlags()</function>
-      performs a userspace reboot only. <constant>SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP</constant> and
+      flags. Since systemd version 257 inhibitors of type <literal>block</literal> are enforced on operations
+      requested by both privileged and unprivileged users. Previously they were honoured only by unprivileged
+      users, excluding the user owning the inhibitor. The latter behaviour is now available through the
+      <literal>block-weak</literal> inhibitor lock type. <constant>SD_LOGIND_ROOT_CHECK_INHIBITORS</constant>
+      (0x01) makes <literal>block-weak</literal> locks behave like regular <literal>block</literal> locks,
+      i.e. ensures they are honoured for any user. A flag <constant>SD_LOGIND_SKIP_INHIBITORS</constant>
+      (0x10) can be specified to bypass both <literal>block</literal> and <literal>block-weak</literal>
+      inhibitors (it has no effect on <literal>delay</literal> inhibitors). When
+      <constant>SD_LOGIND_KEXEC_REBOOT</constant> (0x02) is set, then <function>RebootWithFlags()</function>
+      performs a kexec reboot if kexec kernel is loaded. When <constant>SD_LOGIND_SOFT_REBOOT</constant>
+      (0x04) is set, or <constant>SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP</constant> (0x08) is set and a new
+      root file system has been set up on <literal>/run/nextroot/</literal>, then
+      <function>RebootWithFlags()</function> performs a userspace reboot
+      only. <constant>SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP</constant> and
       <constant>SD_LOGIND_KEXEC_REBOOT</constant> can be combined, with soft-reboot having precedence.
       </para>
 

diff --git a/man/systemd-inhibit.xml b/man/systemd-inhibit.xml
index a8516a5f44ce90c7cbea4ed4e26dbf56a403fe11..27ea6d9836bb408f365c087c43f092c51a0d8fb8 100644 (file)
--- a/man/systemd-inhibit.xml
+++ b/man/systemd-inhibit.xml
@@ -95,13 +95,14 @@
         <listitem><para>Takes <literal>block</literal>, <literal>delay</literal>, or
         <literal>block-weak</literal> and describes how the lock is applied. If <literal>block</literal> is
         used (the default), the lock prohibits any of the requested operations without time limit, and only
-        privileged users may override it. If <literal>delay</literal> is used, the lock can only delay the
-        requested operations for a limited time. If the time elapses, the lock is ignored and the operation
-        executed. The time limit may be specified in
+        privileged users may override it. The <literal>block-weak</literal> inhibitor lock type is similar to
+        <literal>block</literal> but is not enforced against operations initiated by privileged clients or
+        those owned by the user that also owns the inhibitor lock. If <literal>delay</literal> is used, the
+        lock can only delay the requested operations for a limited time. If the time elapses, the lock is
+        ignored and the operation executed. The time limit may be specified in
         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
         Note that <literal>delay</literal> is only available for <literal>sleep</literal> and
-        <literal>shutdown</literal>. In addition, the weak variants will automatically and silently be
-        bypassed under some circumstances.</para></listitem>
+        <literal>shutdown</literal>.</para></listitem>
       </varlistentry>
 
       <varlistentry>