From 9ecf9e414a97e861db403e043696fed6033508f0 Mon Sep 17 00:00:00 2001

From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>

Date: Sun, 14 Aug 2016 16:27:59 -0400

Subject: [PATCH] man: explain that *KeyIgnoreInhibited only apply to a subset

 of locks

Follow-up for #3924.

(cherry picked from commit 05b2a8fd7a0533758d2f532df798cabc3c442683)

---

 man/logind.conf.xml            | 42 ++++++++++++++++++++++++++----------------

 man/systemd-inhibit.xml        |  2 +-

 man/systemd-logind.service.xml |  2 +-

 3 files changed, 28 insertions(+), 18 deletions(-)

diff --git a/man/logind.conf.xml b/man/logind.conf.xml

index adba5a4131..5931832996 100644

--- a/man/logind.conf.xml

+++ b/man/logind.conf.xml

@@ -211,7 +211,7 @@

         <term><varname>HandleLidSwitch=</varname></term>

         <term><varname>HandleLidSwitchDocked=</varname></term>

-        <listitem><para>Controls whether logind shall handle the

+        <listitem><para>Controls how logind shall handle the

         system power and sleep keys and the lid switch to trigger

         actions such as system power-off or suspend. Can be one of

         <literal>ignore</literal>,

@@ -240,7 +240,16 @@

         docking station, or if more than one display is connected, the

         action specified by <varname>HandleLidSwitchDocked=</varname>

         occurs; otherwise the <varname>HandleLidSwitch=</varname>

-        action occurs.</para></listitem>

+        action occurs.</para>

+

+        <para>A different application may disable logind's handling of system power and

+        sleep keys and the lid switch by taking a low-level inhibitor lock

+        ("handle-power-key", "handle-suspend-key", "handle-hibernate-key",

+        "handle-lid-switch"). This is most commonly used by graphical desktop environments

+        to take over suspend and hibernation handling, and to use their own configuration

+        mechanisms. If a low-level inhibitor lock is taken, logind will not take any

+        action when that key or switch is triggered and the <varname>Handle*=</varname>

+        settings are irrelevant.</para></listitem>

       </varlistentry>

       <varlistentry>

@@ -249,21 +258,22 @@

         <term><varname>HibernateKeyIgnoreInhibited=</varname></term>

         <term><varname>LidSwitchIgnoreInhibited=</varname></term>

-        <listitem><para>Controls whether actions triggered by the

-        power and sleep keys and the lid switch are subject to

-        inhibitor locks. These settings take boolean arguments. If

-        <literal>no</literal>, the inhibitor locks taken by

-        applications in order to block the requested operation are

-        respected. If <literal>yes</literal>, the requested operation

-        is executed in any case.

+        <listitem><para>Controls whether actions that <command>systemd-logind</command>

+        takes when the power and sleep keys and the lid switch are triggered are subject

+        to high-level inhibitor locks ("shutdown", "sleep", "idle"). Low level inhibitor

+        locks ("handle-*-key"), are always honoured, irrespective of this setting.</para>

+

+        <para>These settings take boolean arguments. If <literal>no</literal>, the

+        inhibitor locks taken by applications are respected. If <literal>yes</literal>,

+        "shutdown", "sleep", and "idle" inhibitor locks are ignored.

         <varname>PowerKeyIgnoreInhibited=</varname>,

-        <varname>SuspendKeyIgnoreInhibited=</varname> and

-        <varname>HibernateKeyIgnoreInhibited=</varname> default to

-        <literal>no</literal>.

-        <varname>LidSwitchIgnoreInhibited=</varname> defaults to

-        <literal>yes</literal>. This means that the lid switch does

-        not respect suspend blockers by default, but the power and

-        sleep keys do. </para></listitem>

+        <varname>SuspendKeyIgnoreInhibited=</varname>, and

+        <varname>HibernateKeyIgnoreInhibited=</varname> default to <literal>no</literal>.

+        <varname>LidSwitchIgnoreInhibited=</varname> defaults to <literal>yes</literal>.

+        This means that when <command>systemd-logind</command> is handling events by

+        itself (no low level inhibitor locks are taken by another application), the lid

+        switch does not respect suspend blockers by default, but the power and sleep keys

+        do.</para></listitem>

       </varlistentry>

       <varlistentry>

diff --git a/man/systemd-inhibit.xml b/man/systemd-inhibit.xml

index 9d85908f97..ce169960d8 100644

--- a/man/systemd-inhibit.xml

+++ b/man/systemd-inhibit.xml

@@ -61,7 +61,7 @@

     <title>Description</title>

     <para><command>systemd-inhibit</command> may be used to execute a

-    program with a shutdown, sleep or idle inhibitor lock taken. The

+    program with a shutdown, sleep, or idle inhibitor lock taken. The

     lock will be acquired before the specified command line is

     executed and released afterwards.</para>

diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml

index 5733e42cd1..f0bdb1c756 100644

--- a/man/systemd-logind.service.xml

+++ b/man/systemd-logind.service.xml

@@ -84,7 +84,7 @@

       management</para></listitem>

     </itemizedlist>

-    <para>User sessions are registered in logind via the

+    <para>User sessions are registered with logind via the

     <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>

     PAM module.</para>