.TH CONS 3 
.SH NAME
cons \- console, clocks, process/process group ids, user, null, etc.
.SH SYNOPSIS
.nf
.B bind #c /dev

.B /dev/authcheck
.B /dev/authenticate
.B /dev/authenticator
.B /dev/bintime
.B /dev/cons
.B /dev/consctl
.B /dev/cputime
.B /dev/drivers
.B /dev/hostdomain
.B /dev/hostowner
.B /dev/key
.B /dev/null
.B /dev/pgrpid
.B /dev/pid
.B /dev/ppid
.B /dev/random
.B /dev/reboot
.B /dev/swap
.B /dev/sysname
.B /dev/sysstat
.B /dev/time
.B /dev/user
.B /dev/zero
.fi
.SH DESCRIPTION
The console device serves a one-level directory
giving access to the console and
miscellaneous information.
.PP
Reading the
.B cons
file returns characters typed on the keyboard.
Normally, characters are buffered to enable erase and kill processing.
A control-U,
.LR ^U ,
typed at the keyboard
.I kills
the current input line (removes all characters
from the buffer of characters
not yet read via
.BR cons ),
and a backspace
.I 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
.IR utf (6)),
but the runes are translated into the variable-length
.SM UTF
encoding (see
.IR utf (6))
before putting them into the buffer.
A
.IR read (2)
of length greater than zero causes the process to wait until a
newline or a
.L ^D
ends the buffer, and then returns as much of the buffer as the argument
to
.B read
allows, but only up to one complete line.
A terminating
.L ^D
is not put into the buffer.
If part of the line remains, the next
.B read
will return bytes from that remainder and not part of any new line
that has been typed since.
.PP
If
the string
.B rawon
has been written to the
.B consctl
file and the file is still open,
.B cons
is in
.IR "raw mode" :
characters are not echoed as they are typed,
backspace and
.L ^D
are not treated specially,
and characters are available to
.I read
as soon as they are typed.
Ordinary mode is reentered when
.B rawoff
is written to
.B consctl
or this file is closed.
.PP
A
.I write
(see
.IR read (2))
to
.B cons
causes the characters to be printed on the console screen.
.PP
The
.B null
file throws away anything written to it
and always returns zero bytes when read.
.PP
The
.B zero
file is a read-only file that produces an infinite stream of zero-valued bytes when read.
.PP
The
.B drivers
file contains, one per line, a listing of the drivers configured in the kernel, in the format
.IP
.EX
#c cons
.EE
.PP
The
.B hostdomain
file contains the name of the authentication domain that
this host belongs to; see
.IR auth (6).
Only the user named in
.B /dev/hostowner
may write this.
.PP
The
.B hostowner
file contains the name of the user that owns the console device files.
The hostowner also has group permissions for any local devices.
.PP
The
.B key
file is used to set the DES key used for encryption.
Each machine has one key.
Only the user named in
.B /dev/hostowner
may write this.
.PP
The
.B authenticate
file is used to authenticate new users to the kernel; see
.IR auth (6).
After an open, the first read returns a ticket request message
of the following form:
.EX
	char num;
	char authid[28];
	char authdom[48];
	char chal[8];
	char hostid[28];
	char uid[28];
.EE
Here
.I num
is 1,
.I authid
and
.I hostid
are the contents of
.BR hostowner ,
and
.I authdom
is the contents of
.BR hostdomain .
.I Chal
is an 8 byte random challenge created by the kernel.
A subsequent write of a valid ticket encrypted with the key contained in
.B key
changes the user name of the writing process to the value of
.I suid
in the ticket.
The ticket is of the form:
.EX
	char num;
	char chal[8];
	char cuid[28];
	char suid[28];
	char noncekey[7];
.EE
The ticket is valid if
.I num
is 64 and
.I chal
matches the challenge in the ticket request.
Writing an invalid ticket generates an error.
A read following a successful write yields an authenticator
message of the form:
.EX
	char num;
	char chal[8];
	char id[4];
.EE
The authenticator is encrypted in
.I noncekey
from the ticket.
.I Num
is 66,
.IR id [0-4]
are 0,
and
.I chal
matches the challenge in the original ticket request.
.PP
The
.B authenticator
file is used to generate an authenticator from a ticket.
One writes a ticket encrypted with the key contained in
.BR key ,
followed, optionally, by a 4-byte
.IR id ;
a missing
.I id
defaults to zero.
If the client uid matches the current user, a subsequent read yields
an authenticator for that ticket with the given
.IR id .
.PP
The
.B authcheck
file is used to match authenticators to tickets.
A write of an authenticator appended to the end of a ticket
succeeds if the ticket is encrypted with
the key contained in
.BR key ,
the ticket's
.I num
is 65,
the authenticator is encrypted with the ticket's
.BR noncekey ,
the authenticator's and ticket's
.IR chal 's
match, the authenticator's
.I num
is 66, and the authenticator's
.I id
is 0.  Alternatively, the write may consist of ticket, authenticator,
.IR chal ,
and
.IR id ,
in which case the given
.I chal
and
.I id
must match those of the authenticator.
.PP
The
.B user
file contains the name of the user associated with the current process.
Any process can change to user
.B none
by writing
.B none
to this file.
.PP
Reads from
.B 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,
.B random
should be treated as a seed to
pseudo-random number generators which can produce a faster
rate stream.
.PP
Writing the string
.B reboot
to
.B reboot
causes the system to shutdown and, if
possible, restart.   
Only the host
owner has the ability to open this file.
.PP
.B Bintime
is a binary interface that provides
the same information as
.B time
.RI ( q.v. ),
in binary form,
and also controls clock frequency and clock trim.
All integers read or written from
.B bintime
are in big endian 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
.B bintime
returns 24 bytes, three 8 byte numbers, representing nanoseconds
since start of epoch, clock ticks, and clock frequency.
.PP
A write to
.B bintime
is a message with one of 3 formats:
.IP "\f5n\fP<8-byte \f2time\fP>" 1.2i
set the nanoseconds since epoch to the given
.IR time .
.IP "\f5d\fP<8-byte \f2delta\fP><4-byte \f2period\fP>" 1.2i
trim the nanoseconds since epoch by
.I delta
over the next
.I period
seconds.
.IP "\f5f\fP<8-byte \f2freq\fP>" 1.2i
Set the frequency for interpreting clock ticks to be
.I freq
ticks per second.
.PP
The rest of the files contain (mostly) read-only strings.
Each string has a fixed length: a
.IR read (2)
of more than that gives a result of that fixed length (the result does not
include a terminating zero byte);
a
.I 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,
.I 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.  
.PP
The
.B 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.
.PP
The
.B 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.
.PP
A write of a decimal number to
.B time
will set the seconds since epoch.
.PP
The
.B sysname
file holds the textual name of the machine, e.g.
.BR kremvax ,
if known.
.PP
The
.B 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,
.B sysstat
holds one line per processor.
Writing anything to
.B sysstat
resets all of the counts on all processors.
.PP
The
.B swap
device holds a string of the form
.IP
.IB m1 / m2
.B memory
.IB s1 / s2
.B swap
.PP
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
.B swap
the textual file descriptor number of a file or device on which to swap.
See
.IR swap (8).
.PP
The other files served by the
.I cons
device are all single numbers:
.TP 10
.B pgrpid
process group number
.TP
.B pid
process number
.TP
.B ppid
parent's process number
.SH SEE ALSO
.IR draw (3),
.IR keyboard (6),
.IR auth (6),
.IR utf (6),
.IR swap (8)
.SH SOURCE
.B /sys/src/9/port/devcons.c
.SH BUGS
For debugging, two control-T's followed by a letter
generate console output and manage debugging:
.L ^T^Td
toggles whether the console debugger will be run if the system fails.
.L ^T^TD
starts the console debugger immediately.
.L ^T^Tk
kills the largest process; use with care.
.L ^T^Tp
prints data about processes.
.L ^T^Tq
prints the run queue for processor 0.
.L ^T^Ts
prints the kernel stack.
.L ^T^Tx
prints data about kernel memory allocation.
.PP
The system can be rebooted by typing
.LR ^T^Tr .