plan9front/sys/man/3/cons

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

.B /dev/bintime
.B /dev/config
.B /dev/cons
.B /dev/cputime
.B /dev/drivers
.B /dev/hostdomain
.B /dev/hostowner
.B /dev/kmesg
.B /dev/kprint
.B /dev/null
.B /dev/osversion
.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 screen and
miscellaneous information.
.PP
A
.I write
(see
.IR read (2))
to
.B cons
causes the characters to be printed on the console screen. Console
input is handled by a different program (see
.IR kbdfs (8)).
.PP
The
.B 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
.BR 2000 .
.PP
The
.B config
file contains a copy of the kernel configuration file used to build the kernel.
.PP
The
.B kmesg
file holds the last 16 kilobytes of output written to the console
by the kernel's print statements or by processes writing to
.BR /dev/cons .
It is useful for retrieving boot messages once the boot
process is over.
.PP
The
.B 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
.BR /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
.BR kprint ;
if its console is a graphics screen, the data is sent either to the
display or to
.BR kprint ,
but not both.
(It is advisable not to open
.B kprint
on terminals until you have started
.IR rio (1).)
.PP
The
.B null
file throws away anything written to it
and always returns zero 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 authsrv (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
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.
Writing the string
.B reboot
.I kernelpath
loads the named kernel image and restarts,
preserving the kernel configuration in
.BR #ec ,
except that the
.B bootfile
variable is set to
.IR kernelpath .
Writing the string
.B rdb
activates the remote kernel debugger (see
.IR rdbfs (4)).
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 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 percentage units;
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 text block giving memory usage statistics:
.IP
.EX
\fIn\fP memory
\fIn\fP pagesize
\fIn\fP kernel
\fIn\fP/\fIm\fP user
\fIn\fP/\fIm\fP swap
\fIn\fP/\fIm\fP kernel malloc
\fIn\fP/\fIm\fP kernel draw
.EE
.PP
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
.IR n / m
indicates
.I n
used out of
.I m
available.
These numbers are not blank padded.
.PP
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
Reads and writes to
.IR mordor
will inevitably cause the front to fall off.
.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 kbd (3),
.IR kbdfs (8),
.IR keyboard (6),
.IR authsrv (6),
.IR utf (6),
.IR swap (8)
.SH SOURCE
.B /sys/src/9/port/devcons.c