CONS(3) CONS(3)
NAME
cons - console, clocks, process/process group ids, user,
null, reboot, etc.
SYNOPSIS
bind #c /dev
/dev/bintime
/dev/config
/dev/cons
/dev/cputime
/dev/drivers
/dev/hostdomain
/dev/hostowner
/dev/kmesg
/dev/kprint
/dev/mordor
/dev/null
/dev/osversion
/dev/pid
/dev/ppid
/dev/random
/dev/reboot
/dev/sysname
/dev/sysstat
/dev/time
/dev/user
/dev/zero
DESCRIPTION
The console device serves a one-level directory giving
access to the console screen and miscellaneous information.
A write (see read(2)) to cons causes the characters to be
printed on the console screen. Console input is handled by a
different program (see kbdfs(8)).
The osversion file contains a textual representation of the
operating system's version and parameters. At the moment,
it contains one field: the 9P protocol version, currently
2000.
The config file contains a copy of the kernel configuration
file used to build the kernel.
The kmesg file holds the last 16 kilobytes of output written
to the console by the kernel's print statements or by pro-
cesses writing to /dev/cons. It is useful for retrieving
boot messages once the boot process is over.
Page 1 Plan 9 (printed 11/18/24)
CONS(3) CONS(3)
The kprint file may be read to receive a copy of the data
written to the console by the kernel's print statements or
by processes writing to /dev/cons. Only data written after
the file is opened is available. If the machine's console
is a serial line, the data is sent both to the console and
to kprint; if its console is a graphics screen, the data is
sent either to the display or to kprint, but not both. (It
is advisable not to open kprint on terminals until you have
started rio(1).)
The null file throws away anything written to it and always
returns zero when read.
The zero file is a read-only file that produces an infinite
stream of zero-valued bytes when read.
The drivers file contains, one per line, a listing of avail-
able kernel drivers, in the format
#c cons
Each process name group (see fork(2)) maintains a mask of
allowed drivers. A process can modify that mask through
writes to the drivers file. Messages are in the format of:
chdev op devmask
Devmask is a string of driver characters. Op specifies how
devmask is interpreted. Op is one of:
& Permit access to just the drivers specified in devmask.
&~ Permit access to all but the drivers specified in
devmask.
~ Remove access to all devices. Devmask is ignored.
Access may only be removed. No op permits a process to
regain access to a driver once it has been removed. Remov-
ing access to mnt(3) additionally prevents new mounts into
the current namespace. The following removes access to all
drivers except draw(3), cons(3), and fs(3):
chdev & ick
The hostdomain file contains the name of the authentication
domain that this host belongs to; see authsrv(6). Only the
user named in /dev/hostowner may write this.
The hostowner file contains the name of the user that owns
the console device files. The hostowner also has group per-
missions for any local devices.
Page 2 Plan 9 (printed 11/18/24)
CONS(3) CONS(3)
Reads from random return a stream of random bytes produced
by the kernels cryptographic random number generator. The
rate at which data can be read depends on the implementation
and can vary from hundreds of megabytes to just a few hun-
dred bits a second. Therefore, random should be treated as a
seed to pseudo-random number generators which can produce a
faster rate stream.
Writing the string reboot to reboot causes the system to
shutdown and, if possible, restart. Writing the string
reboot kernelpath loads the named kernel image and restarts,
preserving the kernel configuration in #ec, except that the
bootfile variable is set to kernelpath. Writing the string
rdb activates the remote kernel debugger (see rdbfs(4)).
Only the host owner has the ability to open this file.
Bintime is a binary interface that provides the same infor-
mation as time (q.v.), in binary form, and also controls
clock frequency and clock trim. All integers read or writ-
ten from bintime are in big endian order. Unlike the other
files, reads and writes do not affect the offset. There-
fore, there is no need for a seek back to zero between sub-
sequent accesses. A read of bintime returns 24 bytes, three
8 byte numbers, representing nanoseconds since start of
epoch, clock ticks, and clock frequency.
A write to bintime is a message with one of 3 formats:
n<8-byte time>
set the nanoseconds since epoch to the given
time.
d<8-byte delta><4-byte period>
trim the nanoseconds since epoch by delta over
the next period seconds.
f<8-byte freq>
Set the frequency for interpreting clock ticks
to be freq ticks per second.
The rest of the files contain (mostly) read-only strings.
Each string has a fixed length: a read(2) of more than that
gives a result of that fixed length (the result does not
include a terminating zero byte); a read of less than that
length leaves the file offset so the rest of the string (but
no more) will be read the next time. To reread the file
without closing it, seek must be used to reset the offset.
When the file contains numeric data each number is formatted
in decimal. If the binary number fits in 32 bits, it is
formatted as an 11 digit decimal number with leading blanks
and one trailing blank; totaling 12 bytes. Otherwise, it is
formatted as 21 digit decimal numbers with leading blanks
Page 3 Plan 9 (printed 11/18/24)
CONS(3) CONS(3)
and one trailing blank; totaling 22 bytes.
The cputime file holds six 32-bit numbers, containing the
time in milliseconds that the current process has spent in
user mode, system calls, real elapsed time, and then the
time spent, by exited children and their descendants, in
user mode, system calls, and real elapsed time.
The time file holds one 32-bit number representing the sec-
onds since start of epoch and three 64-bit numbers, repre-
senting nanoseconds since start of epoch, clock ticks, and
clock frequency.
A write of a decimal number to time will set the seconds
since epoch.
The sysname file holds the textual name of the machine, e.g.
kremvax, if known.
The sysstat file holds 10 numbers: processor number, context
switches, interrupts, system calls, page faults, TLB faults,
TLB purges, load average, idle time and time spent servicing
interrupts. The load average is in units of milli-CPUs and
is decayed over time; idle time and interrupt time are per-
centage units; the others are total counts from boot time.
If the machine is a multiprocessor, sysstat holds one line
per processor. Writing anything to sysstat resets all of
the counts on all processors.
Reads and writes to mordor will inevitably cause the front
to fall off.
The other files served by the cons device are all single
numbers:
pid process number
ppid parent's process number
SEE ALSO
draw(3), kbd(3), kbdfs(8), keyboard(6), authsrv(6), utf(6),
swap(8)
SOURCE
/sys/src/9/port/devcons.c
Page 4 Plan 9 (printed 11/18/24)