man/systemd-inhibit.xml

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