mirrors/systemd
0
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-11-23 18:23:32 +08:00
Code Issues Packages Projects Releases Wiki Activity
f6793bbcf0
systemd/man/systemd-suspend.service.xml

137 lines
6.6 KiB
XML
Raw Normal View History

man: document systemd-suspend.service
2012-06-26 23:33:11 +08:00
<?xml version='1.0'?> <!--*-nxml-*-->
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 21:40:58 +08:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: use same version in public and system ident.
2023-12-25 22:48:33 +08:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 12:23:58 +08:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
man: document systemd-suspend.service
2012-06-26 23:33:11 +08:00
man: xinclude --help/--version/--no-pager
2014-02-14 03:33:51 +08:00
<refentry id="systemd-suspend.service"
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd-suspend.service</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>systemd-suspend.service</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd-suspend.service</refname>
<refname>systemd-hibernate.service</refname>
<refname>systemd-hybrid-sleep.service</refname>
Rename suspend-to-hibernate to suspend-then-hibernate Per some discussion with Gnome folks, they would prefer this name as it's more descriptive of what's happening.
2018-03-29 00:00:06 +08:00
<refname>systemd-suspend-then-hibernate.service</refname>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
<refname>systemd-sleep</refname>
<refpurpose>System sleep state logic</refpurpose>
</refnamediv>
<refsynopsisdiv>
man: use <simplelist> for file lists in synopsis With <para><filename>…</filename></para>, we get a separate "paragraph" for each line, i.e. entries separated by empty lines. This uses up a lot of space and was only done because docbook makes it hard to insert a newline. In some other places, <literallayout> was used, but then we cannot indent the source text (because the whitespace would end up in the final page). We can get the desired result with <simplelist>. With <simplelist> the items are indented in roff output, but not in html output. In some places this looks better then no indentation, and in others it would probably be better to have no indent. But this is a minor issue and we cannot control that. (I didn't convert all spots. There's a bunch of other man pages which have two lines, e.g. an executable and service file, and it doesn't matter there so much.)
2023-12-14 19:52:03 +08:00
<para><simplelist>
<member><filename>systemd-suspend.service</filename></member>
<member><filename>systemd-hibernate.service</filename></member>
<member><filename>systemd-hybrid-sleep.service</filename></member>
<member><filename>systemd-suspend-then-hibernate.service</filename></member>
<member><filename>/usr/lib/systemd/system-sleep</filename></member>
</simplelist></para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><filename>systemd-suspend.service</filename> is a system
service that is pulled in by <filename>suspend.target</filename>
and is responsible for the actual system suspend. Similarly,
<filename>systemd-hibernate.service</filename> is pulled in by
<filename>hibernate.target</filename> to execute the actual
hibernation. Finally,
<filename>systemd-hybrid-sleep.service</filename> is pulled in by
<filename>hybrid-sleep.target</filename> to execute hybrid
Introduce suspend-to-hibernate (#8274) Suspend to Hibernate is a new sleep method that invokes suspend for a predefined period of time before automatically waking up and hibernating the system. It's similar to HybridSleep however there isn't a performance impact on every suspend cycle. It's intended to use with systems that may have a higher power drain in their supported suspend states to prevent battery and data loss over an extended suspend cycle. Signed-off-by: Mario Limonciello <mario.limonciello@dell.com>
2018-03-08 21:17:33 +08:00
hibernation with system suspend and pulled in by
Rename suspend-to-hibernate to suspend-then-hibernate Per some discussion with Gnome folks, they would prefer this name as it's more descriptive of what's happening.
2018-03-29 00:00:06 +08:00
<filename>suspend-then-hibernate.target</filename> to execute system suspend
Introduce suspend-to-hibernate (#8274) Suspend to Hibernate is a new sleep method that invokes suspend for a predefined period of time before automatically waking up and hibernating the system. It's similar to HybridSleep however there isn't a performance impact on every suspend cycle. It's intended to use with systems that may have a higher power drain in their supported suspend states to prevent battery and data loss over an extended suspend cycle. Signed-off-by: Mario Limonciello <mario.limonciello@dell.com>
2018-03-08 21:17:33 +08:00
with a timeout that will activate hibernate later.</para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
<para>Immediately before entering system suspend and/or
hibernation <filename>systemd-suspend.service</filename> (and the
other mentioned units, respectively) will run all executables in
man: revert dynamic paths for split-usr setups This did not really work out as we had hoped. Trying to do this upstream introduced several problems that probably makes it better suited as a downstream patch after all. At any rate, it is not releaseable in the current state, so we at least need to revert this before the release. * by adjusting the path to binaries, but not do the same thing to the search path we end up with inconsistent man-pages. Adjusting the search path too would be quite messy, and it is not at all obvious that this is worth the effort, but at any rate it would have to be done before we could ship this. * this means that distributed man-pages does not make sense as they depend on config options, and for better or worse we are still distributing man pages, so that is something that definitely needs sorting out before we could ship with this patch. * we have long held that split-usr is only minimally supported in order to boot, and something we hope will eventually go away. So before we start adding even more magic/effort in order to make this work nicely, we should probably question if it makes sense at all.
2015-06-19 01:47:44 +08:00
<filename>/usr/lib/systemd/system-sleep/</filename> and pass two
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
arguments to them. The first argument will be
<literal>pre</literal>, the second either
Introduce suspend-to-hibernate (#8274) Suspend to Hibernate is a new sleep method that invokes suspend for a predefined period of time before automatically waking up and hibernating the system. It's similar to HybridSleep however there isn't a performance impact on every suspend cycle. It's intended to use with systems that may have a higher power drain in their supported suspend states to prevent battery and data loss over an extended suspend cycle. Signed-off-by: Mario Limonciello <mario.limonciello@dell.com>
2018-03-08 21:17:33 +08:00
<literal>suspend</literal>, <literal>hibernate</literal>,
Rename suspend-to-hibernate to suspend-then-hibernate Per some discussion with Gnome folks, they would prefer this name as it's more descriptive of what's happening.
2018-03-29 00:00:06 +08:00
<literal>hybrid-sleep</literal>, or <literal>suspend-then-hibernate</literal>
systemd-sleep: Set SYSTEMD_SLEEP_ACTION for systemd-sleep hooks. When suspend-then-hibernate is called, hooks have no ability to determine which stage of the request is being handled; they only see 'pre' and 'post' with the verb 'suspend-then-hibernate'. This change introduces an environment variable called SYSTEMD_SLEEP_ACTION that contains the name of the action that is processing: 'suspend', 'hibernate', 'hybrid-sleep', or 'suspend-after-failed-hibernate'.
2021-01-08 10:06:30 +08:00
depending on the chosen action. An environment variable called <literal>SYSTEMD_SLEEP_ACTION</literal>
will be set and contain the sleep action that is processing. This is primarily helpful for
<literal>suspend-then-hibernate</literal> where the value of the variable will be <literal>suspend</literal>, <literal>hibernate</literal>,
or <literal>suspend-after-failed-hibernate</literal> in cases where hibernation has failed.
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
Immediately after leaving system suspend and/or hibernation the
same executables are run, but the first argument is now
<literal>post</literal>. All executables in this directory are
executed in parallel, and execution of the action is not continued
sleep: Always freeze user.slice Previously, we'd only freeze user.slice in the case of s2h, because we didn't want the user session to resume while systemd was transitioning from suspend to hibernate. This commit extends this freezing behavior to all sleep modes. We also have an environment variable to disable the freezing behavior outright. This is a necessary workaround for someone that has hooks in /usr/lib/systemd/system-sleep/ which communicate with some process running under user.slice, or if someone is using the proprietary NVIDIA driver which breaks when user.slice is frozen (issue #27559) Fixes #27559
2023-12-24 06:03:42 +08:00
until all executables have finished. Note that <filename>user.slice</filename> will
be frozen while the executables are running, so they should not attempt to
communicate with any user services expecting a reply.</para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
<para>Note that scripts or binaries dropped in
man: revert dynamic paths for split-usr setups This did not really work out as we had hoped. Trying to do this upstream introduced several problems that probably makes it better suited as a downstream patch after all. At any rate, it is not releaseable in the current state, so we at least need to revert this before the release. * by adjusting the path to binaries, but not do the same thing to the search path we end up with inconsistent man-pages. Adjusting the search path too would be quite messy, and it is not at all obvious that this is worth the effort, but at any rate it would have to be done before we could ship this. * this means that distributed man-pages does not make sense as they depend on config options, and for better or worse we are still distributing man pages, so that is something that definitely needs sorting out before we could ship with this patch. * we have long held that split-usr is only minimally supported in order to boot, and something we hope will eventually go away. So before we start adding even more magic/effort in order to make this work nicely, we should probably question if it makes sense at all.
2015-06-19 01:47:44 +08:00
<filename>/usr/lib/systemd/system-sleep/</filename> are intended
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
for local use only and should be considered hacks. If applications
man: update links to "Inhibitor Locks"
2024-05-28 19:04:09 +08:00
want to react to system suspend/hibernation and resume, they should rather use the
<ulink url="https://systemd.io/INHIBITOR_LOCKS">Inhibitor Locks</ulink>.</para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
tree-wide: fixes for assorted grammar and spelling issues Fixes #16363. Also includes some changes where I generalized the pattern.
2020-07-06 16:49:59 +08:00
<para>Note that <filename>systemd-suspend.service</filename>,
<filename>systemd-hibernate.service</filename>, <filename>systemd-hybrid-sleep.service</filename>, and
<filename>systemd-suspend-then-hibernate.service</filename> should never be executed directly. Instead,
trigger system sleep with a command such as <command>systemctl suspend</command> or <command>systemctl
hibernate</command>.</para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
<para>Internally, this service will echo a string like
<literal>mem</literal> into <filename>/sys/power/state</filename>,
to trigger the actual system suspend. What exactly is written
tree-wide: drop quotes from around [section] For users, the square brackets already serve as markup and clearly delineate the section name from surrounding text. Putting additional markup around that only adds clutter. Also, we were very inconsistent in using the quotes. Let's just drop them altogether.
2020-07-06 17:00:06 +08:00
where can be configured in the [Sleep] section
man: revert dynamic paths for split-usr setups This did not really work out as we had hoped. Trying to do this upstream introduced several problems that probably makes it better suited as a downstream patch after all. At any rate, it is not releaseable in the current state, so we at least need to revert this before the release. * by adjusting the path to binaries, but not do the same thing to the search path we end up with inconsistent man-pages. Adjusting the search path too would be quite messy, and it is not at all obvious that this is worth the effort, but at any rate it would have to be done before we could ship this. * this means that distributed man-pages does not make sense as they depend on config options, and for better or worse we are still distributing man pages, so that is something that definitely needs sorting out before we could ship with this patch. * we have long held that split-usr is only minimally supported in order to boot, and something we hope will eventually go away. So before we start adding even more magic/effort in order to make this work nicely, we should probably question if it makes sense at all.
2015-06-19 01:47:44 +08:00
of <filename>/etc/systemd/sleep.conf</filename> or a
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
<filename>sleep.conf.d</filename> file. See
<citerefentry><refentrytitle>systemd-sleep.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
sleep: Always freeze user.slice Previously, we'd only freeze user.slice in the case of s2h, because we didn't want the user session to resume while systemd was transitioning from suspend to hibernate. This commit extends this freezing behavior to all sleep modes. We also have an environment variable to disable the freezing behavior outright. This is a necessary workaround for someone that has hooks in /usr/lib/systemd/system-sleep/ which communicate with some process running under user.slice, or if someone is using the proprietary NVIDIA driver which breaks when user.slice is frozen (issue #27559) Fixes #27559
2023-12-24 06:03:42 +08:00
<para>Note that by default these services freeze <filename>user.slice</filename> while they run. This prevents
the execution of any process in any of the user sessions while the system is entering into and resuming from
sleep. Thus, this prevents the hooks in <filename>/usr/lib/systemd/system-sleep/</filename>, or any other process
for that matter, from communicating with any user session process during sleep.</para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</refsect1>
<refsect1>
<title>Options</title>
<para><command>systemd-sleep</command> understands the
following commands:</para>
<variablelist>
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
<varlistentry>
<term><option>suspend</option></term>
<term><option>hibernate</option></term>
Rename suspend-to-hibernate to suspend-then-hibernate Per some discussion with Gnome folks, they would prefer this name as it's more descriptive of what's happening.
2018-03-29 00:00:06 +08:00
<term><option>suspend-then-hibernate</option></term>
Clarify the behaviour of suspend-then-sleep mode in the manual pages. Fixes #20125.
2021-07-05 17:06:15 +08:00
<term><option>hybrid-sleep</option></term>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
Rename suspend-to-hibernate to suspend-then-hibernate Per some discussion with Gnome folks, they would prefer this name as it's more descriptive of what's happening.
2018-03-29 00:00:06 +08:00
<listitem><para>Suspend, hibernate, suspend then hibernate, or put the
Introduce suspend-to-hibernate (#8274) Suspend to Hibernate is a new sleep method that invokes suspend for a predefined period of time before automatically waking up and hibernating the system. It's similar to HybridSleep however there isn't a performance impact on every suspend cycle. It's intended to use with systems that may have a higher power drain in their supported suspend states to prevent battery and data loss over an extended suspend cycle. Signed-off-by: Mario Limonciello <mario.limonciello@dell.com>
2018-03-08 21:17:33 +08:00
system to hybrid sleep.</para>
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 23:03:38 +08:00
<xi:include href="version-info.xml" xpointer="v203"/>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>See Also</title>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-23 02:09:32 +08:00
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd-sleep.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-halt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
</simplelist></para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</refsect1>
man: document systemd-suspend.service
2012-06-26 23:33:11 +08:00
</refentry>
Reference in New Issue Copy Permalink