.TH runlevel 8 2009-07-09 "Upstart"
.\"
.SH NAME
runlevel \- output previous and current runlevel
.\"
.SH SYNOPSIS
.B runlevel
.RI [ OPTION ]...
.RI [ UTMP ]
.\"
.SH DESCRIPTION
.B runlevel
reads the system
.I UTMP
file, which defaults to
.I /var/run/utmp
when no alternate filename is given, to locate the most recent runlevel
record.

The previous and current runlevel from that record are output separated
by a single space.  If there is no previous runlevel in the record, the letter
.I N
will be substituted.

If no runlevel record can be found,
.B runlevel
outputs the word
.B unknown
and exits with an error.

During system boot, the environment variables
.B RUNLEVEL
and
.B PREVLEVEL
will be set by the
.BR init (8)
daemon, these come from the
.BR runlevel (7)
event generated by
.BR telinit (8)
or
.BR shutdown (8).  

When these environment variables are set,
.B runlevel
will output the values from these instead.  Thus
.B runlevel
can be used in
.I rc
scripts as a replacement for the System-V
.BR who(1)
.B -r
command.
.\"
.SH OPTIONS
.TP
.B --quiet
Does not output the current and previous runlevel, nor does it output
.B unknown
in the case of error (but it will exit with an error code).

This may be used to test for the presence of a runlevel entry, or to check
for errors reading from the file.
.\"
.SH EXIT STATUS
.B runlevel
will exit with status
.I 0
if a
.I UTMP
record was found, otherwise it will exit with status
.IR 1 .
.\"
.SH ENVIRONMENT
.TP
.B RUNLEVEL
.B runlevel
will read the current runlevel from this environment variable if set in
preference to reading from
.I /var/run/utmp
.\"
.TP
.B PREVLEVEL
.B runlevel
will read the previous runlevel from this environment variable if
.B RUNLEVEL
 was given, in preference to reading from
.I /var/run/utmp
.\"
.SH FILES
.TP
.I /var/run/utmp
Where the current and previous runlevels will be read from.
.\"
.SH NOTES
The Upstart
.BR init (8)
daemon does not keep track of runlevels itself, instead they are implemented
entirely by its userspace tools.

A change of runlevel is signalled by the
.BR runlevel (7)
event, generated by either the
.BR telinit (8)
or
.BR shutdown (8)
tools.  This event includes the new runlevel in the
.B RUNLEVEL
environment variable, as well as the previous runlevel (obtained from
their own environment or from
.IR /var/run/utmp )
in the
.B PREVLEVEL
variable.

As well as generating the event, both tools write the new
runlevel back to
.I /var/run/utmp
and append a new entry to
.I /var/log/wtmp.
.\"
.SH AUTHOR
Written by Scott James Remnant
.RB < scott@netsplit.com >
.\"
.SH REPORTING BUGS
Report bugs at
.RB < https://launchpad.net/upstart/+bugs >
.\"
.SH COPYRIGHT
Copyright \(co 2009 Canonical Ltd.
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.\"
.SH SEE ALSO
.BR runlevel (7)
.BR init (8)
.BR telinit (8)
.BR shutdown (8)
.BR who (1)