CONS(3) CONS(3)
NAME
cons - console, clocks, process/process group ids, user,
null, etc.
SYNOPSIS
bind #c /dev
/dev/authcheck
/dev/authenticate
/dev/authenticator
/dev/bintime
/dev/cons
/dev/consctl
/dev/cputime
/dev/drivers
/dev/hostdomain
/dev/hostowner
/dev/key
/dev/null
/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 key-
board. Normally, characters are buffered to enable erase
and kill processing. A control-U, `^U', typed at the key-
board 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 16-bit
runes (see utf(6)), but the runes are translated 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 `^D' ends
the buffer, and then returns as much of the buffer as the
argument to read allows, but only up to one complete line.
Page 1 Plan 9 (printed 12/26/24)
CONS(3) CONS(3)
A terminating `^D' is not put into the buffer. If part of
the line remains, the next read will return bytes from that
remainder 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 `^D' are not
treated specially, and characters are available to read as
soon as they are typed. Ordinary mode is reentered 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 null file throws away anything written to it and always
returns zero bytes 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 configured in the kernel, in the format
#c cons
The hostdomain file contains the name of the authentication
domain that this host belongs to; see auth(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.
The key file is used to set the DES key used for encryption.
Each machine has one key. Only the user named in
/dev/hostowner may write this.
The authenticate file is used to authenticate new users to
the kernel; see auth(6). After an open, the first read
returns a ticket request message of the following form:
char num;
char authid[28];
char authdom[48];
char chal[8];
char hostid[28];
char uid[28];
Here num is 1, authid and hostid are the contents of
hostowner, and authdom is the contents of hostdomain. Chal
is an 8 byte random challenge created by the kernel. A sub-
sequent write of a valid ticket encrypted with the key con-
tained in key changes the user name of the writing process
Page 2 Plan 9 (printed 12/26/24)
CONS(3) CONS(3)
to the value of suid in the ticket. The ticket is of the
form:
char num;
char chal[8];
char cuid[28];
char suid[28];
char noncekey[7];
The ticket is valid if num is 64 and chal matches the chal-
lenge in the ticket request. Writing an invalid ticket gen-
erates an error. A read following a successful write yields
an authenticator message of the form:
char num;
char chal[8];
char id[4];
The authenticator is encrypted in noncekey from the ticket.
Num is 66, id[0-4] are 0, and chal matches the challenge in
the original ticket request.
The authenticator file is used to generate an authenticator
from a ticket. One writes a ticket encrypted with the key
contained in key, followed, optionally, by a 4-byte id; a
missing id defaults to zero. If the client uid matches the
current user, a subsequent read yields an authenticator for
that ticket with the given id.
The authcheck file is used to match authenticators to tick-
ets. A write of an authenticator appended to the end of a
ticket succeeds if the ticket is encrypted with the key con-
tained in key, the ticket's num is 65, the authenticator is
encrypted with the ticket's noncekey, the authenticator's
and ticket's chal's match, the authenticator's num is 66,
and the authenticator's id is 0. Alternatively, the write
may consist of ticket, authenticator, chal, and id, in which
case the given chal and id must match those of the authenti-
cator.
The user file contains the name of the user associated with
the current process. Any process can change to user none by
writing none to this file.
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. Only the host owner has
Page 3 Plan 9 (printed 12/26/24)
CONS(3) CONS(3)
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
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
Page 4 Plan 9 (printed 12/26/24)
CONS(3) CONS(3)
since epoch.
The sysname file holds the textual name of the machine, e.g.
kremvax, if known.
The sysstat file holds 8 numbers: processor number, context
switches, interrupts, system calls, page faults, TLB faults,
TLB purges, and load average. The load average is in units
of milli-CPUs and is decayed over time; 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 string of the form
m1/m2 memory s1/s2 swap
These give, for each of internal memory and the swapping
area, the number of pages used and the total 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), auth(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: `^T^Td' toggles whether
the console debugger will be run if the system fails.
`^T^TD' starts the console debugger immediately. `^T^Tk'
kills the largest process; use with care. `^T^Tp' prints
data about processes. `^T^Tq' prints the run queue for pro-
cessor 0. `^T^Ts' prints the kernel stack. `^T^Tx' prints
data about kernel memory allocation.
The system can be rebooted by typing `^T^Tr'.
Page 5 Plan 9 (printed 12/26/24)