man/systemd-inhibit.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="systemd-inhibit"
  10     xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>systemd-inhibit</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>systemd-inhibit</refentrytitle>
  19     <manvolnum>1</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>systemd-inhibit</refname>
  24     <refpurpose>Execute a program with an inhibition lock taken</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <cmdsynopsis>
  29       <command>systemd-inhibit <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>COMMAND</arg> <arg choice="opt" rep="repeat">ARGUMENTS</arg></command>
  30     </cmdsynopsis>
  31     <cmdsynopsis>
  32       <command>systemd-inhibit <arg choice="opt" rep="repeat">OPTIONS</arg> --list</command>
  33     </cmdsynopsis>
  34   </refsynopsisdiv>
  35
  36   <refsect1>
  37     <title>Description</title>
  38
  39     <para><command>systemd-inhibit</command> may be used to execute a
  40     program with a shutdown, sleep, or idle inhibitor lock taken. The
  41     lock will be acquired before the specified command line is
  42     executed and released afterwards.</para>
  43
  44     <para>Inhibitor locks may be used to block or delay system sleep
  45     and shutdown requests from the user, as well as automatic idle
  46     handling of the OS. This is useful to avoid system suspends while
  47     an optical disc is being recorded, or similar operations that
  48     should not be interrupted.</para>
  49
  50     <para>For more information see the <ulink
  51     url="https://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor
  52     Lock Developer Documentation</ulink>.</para>
  53   </refsect1>
  54
  55   <refsect1>
  56     <title>Options</title>
  57
  58     <para>The following options are understood:</para>
  59
  60     <variablelist>
  61       <varlistentry>
  62         <term><option>--what=</option></term>
  63
  64         <listitem><para>Takes a colon-separated list of one or more
  65         operations to inhibit:
  66         <literal>shutdown</literal>,
  67         <literal>sleep</literal>,
  68         <literal>idle</literal>,
  69         <literal>handle-power-key</literal>,
  70         <literal>handle-suspend-key</literal>,
  71         <literal>handle-hibernate-key</literal>,
  72         <literal>handle-lid-switch</literal>,
  73         for inhibiting reboot/power-off/halt/kexec,
  74         suspending/hibernating, the automatic idle detection, or the
  75         low-level handling of the power/sleep key and the lid switch,
  76         respectively. If omitted, defaults to
  77         <literal>idle:sleep:shutdown</literal>.</para></listitem>
  78       </varlistentry>
  79
  80       <varlistentry>
  81         <term><option>--who=</option></term>
  82
  83         <listitem><para>Takes a short, human-readable descriptive
  84         string for the program taking the lock. If not passed,
  85         defaults to the command line string.</para></listitem>
  86       </varlistentry>
  87
  88       <varlistentry>
  89         <term><option>--why=</option></term>
  90
  91         <listitem><para>Takes a short, human-readable descriptive
  92         string for the reason for taking the lock. Defaults to
  93         "Unknown reason".</para></listitem>
  94       </varlistentry>
  95
  96       <varlistentry>
  97         <term><option>--mode=</option></term>
  98
  99         <listitem><para>Takes either <literal>block</literal> or
 100         <literal>delay</literal> and describes how the lock is
 101         applied. If <literal>block</literal> is used (the default),
 102         the lock prohibits any of the requested operations without
 103         time limit, and only privileged users may override it. If
 104         <literal>delay</literal> is used, the lock can only delay the
 105         requested operations for a limited time. If the time elapses,
 106         the lock is ignored and the operation executed. The time limit
 107         may be specified in
 108         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 109         Note that <literal>delay</literal> is only available for
 110         <literal>sleep</literal> and
 111         <literal>shutdown</literal>.</para></listitem>
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term><option>--list</option></term>
 116
 117         <listitem><para>Lists all active inhibition locks instead of
 118         acquiring one.</para></listitem>
 119       </varlistentry>
 120
 121       <xi:include href="standard-options.xml" xpointer="no-pager" />
 122       <xi:include href="standard-options.xml" xpointer="no-legend" />
 123       <xi:include href="standard-options.xml" xpointer="help" />
 124       <xi:include href="standard-options.xml" xpointer="version" />
 125     </variablelist>
 126
 127   </refsect1>
 128
 129   <refsect1>
 130     <title>Exit status</title>
 131
 132     <para>Returns the exit status of the executed program.</para>
 133   </refsect1>
 134
 135   <refsect1>
 136     <title>Example</title>
 137
 138     <programlisting># systemd-inhibit wodim foobar.iso</programlisting>
 139
 140     <para>This burns the ISO image
 141     <filename>foobar.iso</filename> on a CD using
 142     <citerefentry project='man-pages'><refentrytitle>wodim</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 143     and inhibits system sleeping, shutdown and idle while
 144     doing so.</para>
 145   </refsect1>
 146
 147   <xi:include href="less-variables.xml" />
 148
 149   <refsect1>
 150     <title>See Also</title>
 151     <para>
 152       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 153       <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 154     </para>
 155   </refsect1>
 156
 157 </refentry>