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.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   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 <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>COMMAND</arg> <arg choice="opt" rep="repeat">ARGUMENTS</arg></command>
  27     </cmdsynopsis>
  28     <cmdsynopsis>
  29       <command>systemd-inhibit <arg choice="opt" rep="repeat">OPTIONS</arg> --list</command>
  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 the <ulink
  48     url="https://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor
  49     Lock Developer Documentation</ulink>.</para>
  50   </refsect1>
  51
  52   <refsect1>
  53     <title>Options</title>
  54
  55     <para>The following options are understood:</para>
  56
  57     <variablelist>
  58       <varlistentry>
  59         <term><option>--what=</option></term>
  60
  61         <listitem><para>Takes a colon-separated list of one or more
  62         operations to inhibit:
  63         <literal>shutdown</literal>,
  64         <literal>sleep</literal>,
  65         <literal>idle</literal>,
  66         <literal>handle-power-key</literal>,
  67         <literal>handle-suspend-key</literal>,
  68         <literal>handle-hibernate-key</literal>,
  69         <literal>handle-lid-switch</literal>,
  70         for inhibiting reboot/power-off/halt/kexec,
  71         suspending/hibernating, the automatic idle detection, or the
  72         low-level handling of the power/sleep key and the lid switch,
  73         respectively. If omitted, defaults to
  74         <literal>idle:sleep:shutdown</literal>.</para></listitem>
  75       </varlistentry>
  76
  77       <varlistentry>
  78         <term><option>--who=</option></term>
  79
  80         <listitem><para>Takes a short, human-readable descriptive
  81         string for the program taking the lock. If not passed,
  82         defaults to the command line string.</para></listitem>
  83       </varlistentry>
  84
  85       <varlistentry>
  86         <term><option>--why=</option></term>
  87
  88         <listitem><para>Takes a short, human-readable descriptive
  89         string for the reason for taking the lock. Defaults to
  90         "Unknown reason".</para></listitem>
  91       </varlistentry>
  92
  93       <varlistentry>
  94         <term><option>--mode=</option></term>
  95
  96         <listitem><para>Takes either <literal>block</literal> or
  97         <literal>delay</literal> and describes how the lock is
  98         applied. If <literal>block</literal> is used (the default),
  99         the lock prohibits any of the requested operations without
 100         time limit, and only privileged users may override it. If
 101         <literal>delay</literal> is used, the lock can only delay the
 102         requested operations for a limited time. If the time elapses,
 103         the lock is ignored and the operation executed. The time limit
 104         may be specified in
 105         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 106         Note that <literal>delay</literal> is only available for
 107         <literal>sleep</literal> and
 108         <literal>shutdown</literal>.</para></listitem>
 109       </varlistentry>
 110
 111       <varlistentry>
 112         <term><option>--list</option></term>
 113
 114         <listitem><para>Lists all active inhibition locks instead of
 115         acquiring one.</para></listitem>
 116       </varlistentry>
 117
 118       <xi:include href="standard-options.xml" xpointer="no-pager" />
 119       <xi:include href="standard-options.xml" xpointer="no-legend" />
 120       <xi:include href="standard-options.xml" xpointer="help" />
 121       <xi:include href="standard-options.xml" xpointer="version" />
 122     </variablelist>
 123
 124   </refsect1>
 125
 126   <refsect1>
 127     <title>Exit status</title>
 128
 129     <para>Returns the exit status of the executed program.</para>
 130   </refsect1>
 131
 132   <refsect1>
 133     <title>Example</title>
 134
 135     <programlisting># systemd-inhibit wodim foobar.iso</programlisting>
 136
 137     <para>This burns the ISO image
 138     <filename>foobar.iso</filename> on a CD using
 139     <citerefentry project='man-pages'><refentrytitle>wodim</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 140     and inhibits system sleeping, shutdown and idle while
 141     doing so.</para>
 142   </refsect1>
 143
 144   <xi:include href="less-variables.xml" />
 145
 146   <refsect1>
 147     <title>See Also</title>
 148     <para>
 149       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 150       <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 151     </para>
 152   </refsect1>
 153
 154 </refentry>