CONS(3) CONS(3)
NAME
cons - console, clocks, process/process group ids, user,
null, klog, stats, lights, noise, sysstat, hz, swap, crypt,
chal, key
SYNOPSIS
bind #c /dev
/dev/chal
/dev/clock
/dev/cons
/dev/consctl
/dev/cputime
/dev/crypt
/dev/hz
/dev/key
/dev/klog
/dev/lights
/dev/msec
/dev/noise
/dev/null
/dev/pgrpid
/dev/pid
/dev/ppid
/dev/swap
/dev/sysname
/dev/sysstat
/dev/time
/dev/user
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.
A terminating `^D' is not put into the buffer. If part of
Page 1 Plan 9 (printed 4/18/24)
CONS(3) CONS(3)
the line remains, the next read will return characters 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 klog file contains the tail of messages written by ker-
nel logging statements.
Writing a number (as plain text) to the lights device
directs any lights that are available to turn on and off.
The bits of the number are mapped to the lights in a
processor-dependent way.
Writing two blank- or tab- separated numbers to the noise
device causes the machine to make a tone, if possible. The
first number is the frequency, in Hertz, and the second is
the duration, in milliseconds.
The crypt file performs DES encryption. To encrypt data,
first a character `E' (0x45) is written to the file, and
then the data, which must be at least 8 bytes long. Data
longer that 127 bytes is truncated. Data is encrypted with
the same algorithm used in encrypt(2). The encrypted data
can then be read from the file. A similar procedure is used
to decrypt data, except an ASCII `D' (0x44) is written to
the file before the data.
The key file is used to set the DES key used for encryption;
the key is shared within a process group (see auth(6)).
The chal file is used for authenticated setting of the user
name. When read, it returns an encrypted challenge string
to be used for authenticating the user's identity. When
written with the appropriate string, the user name and
encryption key are set. The format of the strings is docu-
mented in auth(6).
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
Page 2 Plan 9 (printed 4/18/24)
CONS(3) CONS(3)
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 format-
ted in decimal as an 11-digit number with leading blanks and
one trailing blank: twelve bytes total.
The user file contains the name of the user associated with
the current process.
The cputime file holds 6 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 clock file holds two numbers: the number of clock ticks
since booting followed by the number of clock ticks in a
second.
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. If the machine is a multipro-
cessor, sysstat holds one line per processor. Writing any-
thing 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:
hz frequency of the system clock
msec number of milliseconds since booting
pgrpid process group number
pid process number
ppid parent's process number
Page 3 Plan 9 (printed 4/18/24)
CONS(3) CONS(3)
time number of seconds since the epoch 00:00:00 GMT,
Jan. 1, 1970. (Can be written once, to set at
boot time.)
SEE ALSO
bit(3), keyboard(6), auth(6), utf(6)
BUGS
For debugging, two control-T's followed by a letter generate
console output: `^T^Tp' prints data about processes, `^T^Tq'
prints data about streams, `^T^Tm' prints data about the
mount device, `^T^Tb' prints data about the bitblt device,
and `^T^Tx' prints date about kernel memory allocation.
The system can be rebooted by typing `^T^Tr.'
Page 4 Plan 9 (printed 4/18/24)