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