chiark / gitweb /
include <poll.h> instead of <sys/poll.h>
[elogind.git] / 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>