docs/INHIBITOR_LOCKS.md

   1 ---
   2 title: Inhibitor Locks
   3 category: Documentation for Developers
   4 layout: default
   5 SPDX-License-Identifier: LGPL-2.1-or-later
   6 ---
   7
   8 # Inhibitor Locks
   9
  10 systemd 183 and newer include a logic to inhibit system shutdowns and sleep states. This is implemented as part of [systemd-logind.daemon(8)](http://www.freedesktop.org/software/systemd/man/systemd-logind.service.html) There are a couple of different use cases for this:
  11
  12 - A CD burning application wants to ensure that the system is not turned off or suspended while the burn process is in progress.
  13
  14 - A package manager wants to ensure that the system is not turned off while a package upgrade is in progress.
  15
  16 - An office suite wants to be notified before system suspend in order to save all data to disk, and delay the suspend logic until all data is written.
  17
  18 - A web browser wants to be notified before system hibernation in order to free its cache to minimize the amount of memory that needs to be virtualized.
  19
  20 - A screen lock tool wants to bring up the screen lock right before suspend, and delay the suspend until that's complete.
  21
  22 Applications which want to make use of the inhibition logic shall take an inhibitor lock via the [logind D-Bus API](https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.login1.html).
  23
  24 Seven distinct inhibitor lock types may be taken, or a combination of them:
  25
  26 1. _sleep_ inhibits system suspend and hibernation requested by (unprivileged) **users**
  27 2. _shutdown_ inhibits high-level system power-off and reboot requested by (unprivileged) **users**
  28 3. _idle_ inhibits that the system goes into idle mode, possibly resulting in **automatic** system suspend or shutdown depending on configuration.
  29
  30 - _handle-power-key_ inhibits the low-level (i.e. logind-internal) handling of the system power **hardware** key, allowing (possibly unprivileged) external code to handle the event instead.
  31
  32 4. Similar, _handle-suspend-key_ inhibits the low-level handling of the system **hardware** suspend key.
  33 5. Similar, _handle-hibernate-key_ inhibits the low-level handling of the system **hardware** hibernate key.
  34 6. Similar, _handle-lid-switch_ inhibits the low-level handling of the systemd **hardware** lid switch.
  35
  36 Two different modes of locks are supported:
  37
  38 1. _block_ inhibits operations entirely until the lock is released.
  39 If such a lock is taken the operation will fail (but still may be overridden if the user possesses the necessary privileges).
  40
  41 2. _delay_ inhibits operations only temporarily, either until the lock is released or up to a certain amount of time.
  42 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.
  43 This mode is only available for _sleep_ and _shutdown_ locks.
  44
  45 Inhibitor locks are taken via the Inhibit() D-Bus call on the logind Manager object:
  46
  47 ```
  48 $ gdbus introspect --system --dest org.freedesktop.login1 --object-path /org/freedesktop/login1
  49 node /org/freedesktop/login1 {
  50   interface org.freedesktop.login1.Manager {
  51     methods:
  52       Inhibit(in  s what,
  53               in  s who,
  54               in  s why,
  55               in  s mode,
  56               out h fd);
  57       ListInhibitors(out a(ssssuu) inhibitors);
  58       ...
  59     signals:
  60       PrepareForShutdown(b active);
  61       PrepareForSleep(b active);
  62       ...
  63     properties:
  64       readonly s BlockInhibited = '';
  65       readonly s DelayInhibited = '';
  66       readonly t InhibitDelayMaxUSec = 5000000;
  67       readonly b PreparingForShutdown = false;
  68       readonly b PreparingForSleep = false;
  69       ...
  70   };
  71   ...
  72 };
  73 ```
  74
  75 **Inhibit()** is the only API necessary to take a lock. It takes four arguments:
  76
  77 - _What_ is a colon-separated list of lock types, i.e. `shutdown`, `sleep`, `idle`, `handle-power-key`, `handle-suspend-key`, `handle-hibernate-key`, `handle-lid-switch`. Example: "shutdown:idle"
  78 - _Who_ is a human-readable, descriptive string of who is taking the lock. Example: "Package Updater"
  79 - _Why_ is a human-readable, descriptive string of why the lock is taken. Example: "Package Update in Progress"
  80 - _Mode_ is one of `block` or `delay`, see above. Example: "block"
  81
  82 Inhibit() returns a single value, a file descriptor that encapsulates the lock.
  83 As soon as the file descriptor is closed (and all its duplicates) the lock is automatically released.
  84 If the client dies while the lock is taken the kernel automatically closes the file descriptor so that the lock is automatically released.
  85
  86 A delay lock taken this way should be released ASAP on reception of PrepareForShutdown(true) (see below), but of course only after execution of the actions the application wanted to delay the operation for in the first place.
  87
  88 **ListInhibitors()** lists all currently active inhibitor locks. It returns an array of structs, each consisting of What, Who, Why, Mode as above, plus the PID and UID of the process that requested the lock.
  89
  90 The **PrepareForShutdown()** and **PrepareForSleep()** signals are emitted when a system suspend or shutdown has been requested and is about to be executed, as well as after the suspend/shutdown was completed (or failed).
  91
  92 The signals carry a boolean argument.
  93 If _True_ the shutdown/sleep has been requested, and the preparation phase for it begins, if _False_ the operation has finished completion (or failed).
  94
  95 If _True_, this should be used as indication for applications to quickly execute the operations they wanted to execute before suspend/shutdown and then release any delay lock taken.
  96 If _False_ the suspend/shutdown operation is over, either successfully or unsuccessfully (of course, this signal will never be sent if a shutdown request was successful).
  97
  98 The signal with _False_ is generally delivered only after the system comes back from suspend, the signal with _True_ possibly as well, for example when no delay lock was taken in the first place, and the system suspend hence executed without any delay.
  99
 100 The signal with _False_ is usually the signal on which applications request a new delay lock in order to be synchronously notified about the next suspend/shutdown cycle.
 101
 102 Note that watching PrepareForShutdown(true)/PrepareForSleep(true) without taking a delay lock is racy and should not be done, as any code that an application might want to execute on this signal might not actually finish before the suspend/shutdown cycle is executed.
 103
 104 _Again_: if you watch PrepareForShutdown(true)/PrepareForSleep(true), then you really should have taken a delay lock first. PrepareForSleep(false) may be subscribed to by applications which want to be notified about system resume events.
 105
 106 Note that this will only be sent out for suspend/resume cycles done via logind, i.e. generally only for high-level user-induced suspend cycles, and not automatic, low-level kernel induced ones which might exist on certain devices with more aggressive power management.
 107
 108 The **BlockInhibited** and **DelayInhibited** properties encode what types of locks are currently taken. These fields are a colon separated list of `shutdown`, `sleep`, `idle`, `handle-power-key`, `handle-suspend-key`, `handle-hibernate-key`, `handle-lid-switch`. The list is basically the union of the What fields of all currently active locks of the specific mode.
 109
 110 **InhibitDelayMaxUSec** contains the delay timeout value as configured in [logind.conf(5)](http://www.freedesktop.org/software/systemd/man/logind.conf.html).
 111
 112 The **PreparingForShutdown** and **PreparingForSleep** boolean properties are true between the two PrepareForShutdown() resp PrepareForSleep() signals that are sent out.
 113 Note that these properties do not trigger PropertyChanged signals.
 114
 115 ## Taking Blocking Locks
 116
 117 Here's the basic scheme for applications which need blocking locks such as a package manager or CD burning application:
 118
 119 1. Take the lock
 120 2. Do your work you don't want to see interrupted by system sleep or shutdown
 121 3. Release the lock
 122
 123 Example pseudo code:
 124
 125 ```
 126 fd = Inhibit("shutdown:idle", "Package Manager", "Upgrade in progress...", "block");
 127 /* ...
 128       do your work
 129                  ... */
 130 close(fd);
 131 ```
 132
 133 ## Taking Delay Locks
 134
 135 Here's the basic scheme for applications which need delay locks such as a web browser or office suite:
 136
 137 1. As you open a document, take the delay lock
 138 2. As soon as you see PrepareForSleep(true), save your data, then release the lock
 139 3. As soon as you see PrepareForSleep(false), take the delay lock again, continue as before.
 140
 141 Example pseudo code:
 142
 143 ```
 144 int fd = -1;
 145
 146 takeLock() {
 147         if (fd >= 0)
 148                 return;
 149
 150         fd = Inhibit("sleep", "Word Processor", "Save any unsaved data in time...", "delay");
 151 }
 152
 153 onDocumentOpen(void) {
 154         takeLock();
 155 }
 156
 157 onPrepareForSleep(bool b) {
 158         if (b) {
 159                 saveData();
 160                 if (fd >= 0) {
 161                         close(fd);
 162                         fd = -1;
 163                 }
 164          } else
 165                 takeLock();
 166
 167 }
 168
 169 ```
 170
 171 ## Taking Key Handling Locks
 172
 173 By default logind will handle the power and sleep keys of the machine, as well as the lid switch in all states.
 174
 175 This ensures that this basic system behavior is guaranteed to work in all circumstances, on text consoles as well as on all graphical environments.
 176
 177 However, some DE might want to do their own handling of these keys, for example in order to show a pretty dialog box before executing the relevant operation, or to simply disable the action under certain conditions.
 178 For these cases the handle-power-key, handle-suspend-key, handle-hibernate-key and handle-lid-switch type inhibitor locks are available.
 179
 180 When taken, these locks simply disable the low-level handling of the keys, they have no effect on system suspend/hibernate/poweroff executed with other mechanisms than the hardware keys (such as the user typing "systemctl suspend" in a shell).
 181
 182 A DE intending to do its own handling of these keys should simply take the locks at login time, and release them on logout; alternatively it might make sense to take this lock only temporarily under certain circumstances
 183 (e.g. take the lid switch lock only when a second monitor is plugged in, in order to support the common setup where people close their laptops when they have the big screen connected).
 184
 185 These locks need to be taken in the "block" mode, "delay" is not supported for them.
 186
 187 If a DE wants to ensure the lock screen for the eventual resume is on the screen before the system enters suspend state, it should do this via a suspend delay inhibitor block (see above).
 188
 189 ## Miscellanea
 190
 191 Taking inhibitor locks is a privileged operation. Depending on the action _org.freedesktop.login1.inhibit-block-shutdown_, _org.freedesktop.login1.inhibit-delay-shutdown_, _org.freedesktop.login1.inhibit-block-sleep_, _org.freedesktop.login1.inhibit-delay-sleep_, _org.freedesktop.login1.inhibit-block-idle_, _org.freedesktop.login1.inhibit-handle-power-key_, _org.freedesktop.login1.inhibit-handle-suspend-key_, _org.freedesktop.login1.inhibit-handle-hibernate-key_,_org.freedesktop.login1.inhibit-handle-lid-switch_.
 192
 193 In general it should be assumed that delay locks are easier to obtain than blocking locks, simply because their impact is much more minimal.
 194 Note that the policy checks for Inhibit() are never interactive.
 195
 196 Inhibitor locks should not be misused.
 197 For example taking idle blocking locks without a very good reason might cause mobile devices to never auto-suspend.
 198 This can be quite detrimental for the battery.
 199
 200 If an application finds a lock denied it should not consider this much of an error and just continue its operation without the protecting lock.
 201
 202 The tool [systemd-inhibit(1)](http://www.freedesktop.org/software/systemd/man/systemd-inhibit.html) may be used to take locks or list active locks from the command line.
 203
 204 Note that gnome-session also provides an [inhibitor API](http://people.gnome.org/~mccann/gnome-session/docs/gnome-session.html#org.gnome.SessionManager.Inhibit), which is very similar to the one of systemd.
 205 Internally, locks taken on gnome-session's interface will be forwarded to logind, hence both APIs are supported.
 206
 207 While both offer similar functionality they do differ in some regards.
 208 For obvious reasons gnome-session can offer logout locks and screensaver avoidance locks which logind lacks.
 209
 210 logind's API OTOH supports delay locks in addition to block locks like GNOME.
 211 Also, logind is available to system components, and centralizes locks from all users, not just those of a specific one.
 212
 213 In general: if in doubt it is probably advisable to stick to the GNOME locks, unless there is a good reason to use the logind APIs directly.
 214 When locks are to be enumerated it is better to use the logind APIs however, since they also include locks taken by system services and other users.