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-or-later -->
5
6<refentry id="runlevel" conditional='HAVE_SYSV_COMPAT'
7    xmlns:xi="http://www.w3.org/2001/XInclude">
8
9  <refentryinfo>
10    <title>runlevel</title>
11    <productname>systemd</productname>
12  </refentryinfo>
13
14  <refmeta>
15    <refentrytitle>runlevel</refentrytitle>
16    <manvolnum>8</manvolnum>
17  </refmeta>
18
19  <refnamediv>
20    <refname>runlevel</refname>
21    <refpurpose>Print previous and current SysV runlevel</refpurpose>
22  </refnamediv>
23
24  <refsynopsisdiv>
25    <cmdsynopsis>
26      <command>runlevel</command>
27      <arg choice="opt" rep="repeat">options</arg>
28    </cmdsynopsis>
29  </refsynopsisdiv>
30
31  <refsect1>
32    <title>Overview</title>
33
34    <para>"Runlevels" are an obsolete way to start and stop groups of
35    services used in SysV init. systemd provides a compatibility layer
36    that maps runlevels to targets, and associated binaries like
37    <command>runlevel</command>. Nevertheless, only one runlevel can
38    be "active" at a given time, while systemd can activate multiple
39    targets concurrently, so the mapping to runlevels is confusing
40    and only approximate. Runlevels should not be used in new code,
41    and are mostly useful as a shorthand way to refer the matching
42    systemd targets in kernel boot parameters.</para>
43
44    <table>
45      <title>Mapping between runlevels and systemd targets</title>
46      <tgroup cols='2' align='left' colsep='1' rowsep='1'>
47        <colspec colname="runlevel" />
48        <colspec colname="target" />
49        <thead>
50          <row>
51            <entry>Runlevel</entry>
52            <entry>Target</entry>
53          </row>
54        </thead>
55        <tbody>
56          <row>
57            <entry>0</entry>
58            <entry><filename>poweroff.target</filename></entry>
59          </row>
60          <row>
61            <entry>1</entry>
62            <entry><filename>rescue.target</filename></entry>
63          </row>
64          <row>
65            <entry>2, 3, 4</entry>
66            <entry><filename>multi-user.target</filename></entry>
67          </row>
68          <row>
69            <entry>5</entry>
70            <entry><filename>graphical.target</filename></entry>
71          </row>
72          <row>
73            <entry>6</entry>
74            <entry><filename>reboot.target</filename></entry>
75          </row>
76        </tbody>
77      </tgroup>
78    </table>
79  </refsect1>
80
81  <refsect1>
82    <title>Description</title>
83
84    <para><command>runlevel</command> prints the previous and current
85    SysV runlevel if they are known.</para>
86
87    <para>The two runlevel characters are separated by a single space
88    character. If a runlevel cannot be determined, N is printed
89    instead. If neither can be determined, the word "unknown" is
90    printed.</para>
91
92    <para>Unless overridden in the environment, this will check the
93    utmp database for recent runlevel changes.</para>
94  </refsect1>
95
96  <refsect1>
97    <title>Options</title>
98
99    <para>The following option is understood:</para>
100
101    <variablelist>
102      <varlistentry>
103        <term><option>--help</option></term>
104
105        <xi:include href="standard-options.xml" xpointer="help-text" />
106      </varlistentry>
107    </variablelist>
108
109  </refsect1>
110
111  <refsect1>
112    <title>Exit status</title>
113
114    <para>If one or both runlevels could be determined, 0 is returned,
115    a non-zero failure code otherwise.</para>
116
117  </refsect1>
118
119  <refsect1>
120    <title>Environment</title>
121
122    <variablelist class='environment-variables'>
123      <varlistentry>
124        <term><varname>$RUNLEVEL</varname></term>
125
126        <listitem><para>If <varname>$RUNLEVEL</varname> is set,
127        <command>runlevel</command> will print this value as current
128        runlevel and ignore utmp.</para></listitem>
129      </varlistentry>
130
131      <varlistentry>
132        <term><varname>$PREVLEVEL</varname></term>
133
134        <listitem><para>If <varname>$PREVLEVEL</varname> is set,
135        <command>runlevel</command> will print this value as previous
136        runlevel and ignore utmp.</para></listitem>
137      </varlistentry>
138    </variablelist>
139  </refsect1>
140
141  <refsect1>
142    <title>Files</title>
143
144    <variablelist>
145      <varlistentry>
146        <term><filename>/run/utmp</filename></term>
147
148        <listitem><para>The utmp database <command>runlevel</command> reads the previous and current runlevel
149        from.</para></listitem>
150      </varlistentry>
151    </variablelist>
152  </refsect1>
153
154  <refsect1>
155    <title>See Also</title>
156    <para>
157      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
158      <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
159      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
160    </para>
161  </refsect1>
162</refentry>
163