term% cat index.txt CONS(3) Library Functions Manual 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/consctl
/dev/cputime
/dev/drivers
/dev/hostdomain
/dev/hostowner
/dev/kmesg
/dev/kprint
/dev/null
/dev/osversion
/dev/pgrpid
/dev/pid
/dev/ppid
/dev/random
/dev/reboot
/dev/swap
/dev/sysname
/dev/sysstat
/dev/time
/dev/user
/dev/zero
DESCRIPTION
The console device serves a one-level directory giving access to the
console and miscellaneous information.
Reading the cons file returns characters typed on the keyboard. Nor‐
mally, characters are buffered to enable erase and kill processing. A
control-U, typed at the keyboard kills the current input line (removes
all characters from the buffer of characters not yet read via cons),
and a backspace erases the previous non-kill, non-erase character from
the input buffer. Killing and erasing only delete characters back to,
but not including, the last newline. Characters typed at the keyboard
actually produce 21-bit runes (see utf(6)), but the runes are trans‐
lated into the variable-length UTF encoding (see utf(6)) before putting
them into the buffer. A read(2) of length greater than zero causes the
process to wait until a newline or a ends the buffer, and then returns
as much of the buffer as the argument to read allows, but only up to
one complete line. A terminating is not put into the buffer. If part
of the line remains, the next read will return bytes from that remain‐
der and not part of any new line that has been typed since.
If the string rawon has been written to the consctl file and the file
is still open, cons is in raw mode: characters are not echoed as they
are typed, backspace, and are not treated specially, and characters are
available to read as soon as they are typed. Ordinary mode is reen‐
tered when rawoff is written to consctl or this file is closed.
A write (see read(2)) to cons causes the characters to be printed on
the console screen.
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 processes writing to
/dev/cons. It is useful for retrieving boot messages once the boot
process is over.
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 advis‐
able 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 the drivers con‐
figured in the kernel, in the format
#c cons
The hostdomain file contains the name of the authentication domain that
this host belongs to; see authsrv(6). Only the user named in /dev/hos‐
towner may write this.
The hostowner file contains the name of the user that owns the console
device files. The hostowner also has group permissions for any local
devices.
Reads from random return a stream of random numbers. The numbers are
generated by a low priority kernel process that loops incrementing a
variable. Each clock tick the variable is sampled and, if it has
changed sufficiently, the last few bits are appended to a buffer. This
process is inefficient at best producing at most a few hundred 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. Only the
host owner has the ability to open this file. The named kernel may be
a Plan 9 executable or a 32-bit or 64-bit ELF executable. On some ar‐
chitectures (e.g., mips), it may also be a Plan 9 boot image.
Bintime is a binary interface that provides the same information as
time (q.v.), in binary form, and also controls clock frequency and
clock trim. All integers read or written from bintime are in big en‐
dian order. Unlike the other files, reads and writes do not affect the
offset. Therefore, there is no need for a seek back to zero between
subsequent 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 pe‐
riod seconds.
f<8-byte freq>
Set the frequency for interpreting clock ticks to be freq
ticks per second.
Statistics and Dynamic Status
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 and one trailing blank; totaling 22 bytes.
The cputime file holds six 32-bit numbers, containing the time in mil‐
liseconds 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 seconds since
start of epoch and three 64-bit numbers, representing 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 av‐
erage, idle time and time spent servicing interrupts. The load average
is in units of milli-CPUs and is decayed over time; idle time and in‐
terrupt time are percentage 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.
The swap device holds a text block giving memory usage statistics:
n memory
n pagesize
n kernel
n/m user
n/m swap
n/m kernel malloc
n/m kernel draw
These are total memory (bytes), system page size (bytes), kernel memory
(pages), user memory (pages), swap space (pages), kernel malloced data
(bytes), and kernel graphics data (bytes). The expression n/m indi‐
cates n used out of m available. These numbers are not blank padded.
To turn on swapping, write to swap the textual file descriptor number
of a file or device on which to swap. See swap(8).
The other files served by the cons device are all single numbers:
pgrpid process group number
pid process number
ppid parent's process number
SEE ALSO
draw(3), keyboard(6), authsrv(6), utf(6), swap(8)
SOURCE
/sys/src/9/port/devcons.c
BUGS
For debugging, two control-T's followed by a letter generate console
output and manage debugging: toggles whether the console debugger will
be run if the system fails. starts the console debugger immediately.
kills the largest process; use with care. prints data about processes.
prints the run queue for processor 0. prints the kernel stack. prints
data about kernel memory allocation.
The system can be rebooted by typing
CONS(3)