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   This file is part of systemd.
   7
   8   Copyright 2012 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="systemd-inhibit">
  25
  26         <refentryinfo>
  27                 <title>systemd-inhibit</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                 </authorgroup>
  38         </refentryinfo>
  39
  40         <refmeta>
  41                 <refentrytitle>systemd-inhibit</refentrytitle>
  42                 <manvolnum>1</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>systemd-inhibit</refname>
  47                 <refpurpose>Execute a program with an inhibition lock taken</refpurpose>
  48         </refnamediv>
  49
  50         <refsynopsisdiv>
  51                 <cmdsynopsis>
  52                         <command>systemd-inhibit <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>COMMAND</arg> <arg choice="opt" rep="repeat">ARGUMENTS</arg></command>
  53                 </cmdsynopsis>
  54                 <cmdsynopsis>
  55                         <command>systemd-inhibit <arg choice="opt" rep="repeat">OPTIONS</arg> --list</command>
  56                 </cmdsynopsis>
  57         </refsynopsisdiv>
  58
  59         <refsect1>
  60                 <title>Description</title>
  61
  62                 <para><command>systemd-inhibit</command> may be used
  63                 to execute a program with a shutdown, sleep or idle
  64                 inhibitor lock taken. The lock will be acquired before
  65                 the specified command line is executed and released
  66                 afterwards.</para>
  67
  68                 <para>Inhibitor locks may be used to block or delay
  69                 system sleep and shutdown requests from the user, as well
  70                 as automatic idle handling of the OS. This is useful
  71                 to avoid system suspends while an optical disc is
  72                 being recorded, or similar operations that should not
  73                 be interrupted.</para>
  74
  75                 <para>For more information see the <ulink
  76                 url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor
  77                 Lock Developer Documentation</ulink>.</para>
  78         </refsect1>
  79
  80         <refsect1>
  81                 <title>Options</title>
  82
  83                 <para>The following options are understood:</para>
  84
  85                 <variablelist>
  86                         <varlistentry>
  87                                 <term><option>-h</option></term>
  88                                 <term><option>--help</option></term>
  89
  90                                 <listitem><para>Prints a short help
  91                                 text and exits.</para></listitem>
  92                         </varlistentry>
  93
  94                         <varlistentry>
  95                                 <term><option>--version</option></term>
  96
  97                                 <listitem><para>Prints a short version
  98                                 string and exits.</para></listitem>
  99                         </varlistentry>
 100
 101                         <varlistentry>
 102                                 <term><option>--what=</option></term>
 103
 104                                 <listitem><para>Takes a colon
 105                                 separated list of one or more
 106                                 operations to inhibit:
 107                                 <literal>shutdown</literal>,
 108                                 <literal>sleep</literal>,
 109                                 <literal>idle</literal>, for
 110                                 inhibiting
 111                                 reboot/power-off/halt/kexec,
 112                                 suspending/hibernating, resp. the
 113                                 automatic idle detection. If ommitted
 114                                 defaults to
 115                                 <literal>idle:sleep:shutdown</literal>,
 116                                 i.e. takes all possible
 117                                 locks.</para></listitem>
 118                         </varlistentry>
 119
 120                         <varlistentry>
 121                                 <term><option>--who=</option></term>
 122
 123                                 <listitem><para>Takes a short human
 124                                 readable descriptive string for the
 125                                 program taking the lock. If not passed
 126                                 defaults to the command line
 127                                 string.</para></listitem>
 128                         </varlistentry>
 129
 130                         <varlistentry>
 131                                 <term><option>--why=</option></term>
 132
 133                                 <listitem><para>Takes a short human
 134                                 readable descriptive string for the
 135                                 reason for taking the lock. Defaults
 136                                 to "Unknown reason".</para></listitem>
 137                         </varlistentry>
 138
 139                         <varlistentry>
 140                                 <term><option>--mode=</option></term>
 141
 142                                 <listitem><para>Takes either
 143                                 <literal>block</literal> or
 144                                 <literal>delay</literal> and describes
 145                                 how the lock is applied. If
 146                                 <literal>block</literal> is used (the
 147                                 default), the lock prohibits any of
 148                                 the requested operations without time
 149                                 limit, and only privileged users may
 150                                 override it. If
 151                                 <literal>delay</literal> is used, the
 152                                 lock can only delay the requested
 153                                 operations for a limited time. If the
 154                                 time elapses the lock is ignored and
 155                                 the operation executed. The time limit
 156                                 may be specified in
 157                                 <citerefentry><refentrytitle>systemd-logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
 158                         </varlistentry>
 159
 160                         <varlistentry>
 161                                 <term><option>--list</option></term>
 162
 163                                 <listitem><para>Lists all active
 164                                 inhibition locks instead of acquiring
 165                                 one.</para></listitem>
 166                         </varlistentry>
 167                 </variablelist>
 168
 169         </refsect1>
 170
 171         <refsect1>
 172                 <title>Exit status</title>
 173
 174                 <para>Returns the exit status of the executed program.</para>
 175         </refsect1>
 176
 177         <refsect1>
 178                 <title>Example</title>
 179
 180                 <programlisting># systemd-inhibit wodim foobar.iso</programlisting>
 181
 182                 <para>This burns the ISO image
 183                 <filename>foobar.iso</filename> on a CD using
 184                 <citerefentry><refentrytitle>wodim</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 185                 and inhibits system sleeping, shutdown and idle while
 186                 doing so.</para>
 187         </refsect1>
 188
 189         <refsect1>
 190                 <title>See Also</title>
 191                 <para>
 192                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 193                         <citerefentry><refentrytitle>systemd-logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 194                 </para>
 195         </refsect1>
 196
 197 </refentry>