build: Better Build System

1 files changed, 346 insertions, 0 deletions

diff --git a/static/plan9-4e/man3/cons.3 b/static/plan9-4e/man3/cons.3
new file mode 100644
index 00000000..0d4de988
--- /dev/null
+++ b/static/plan9-4e/man3/cons.3
@@ -0,0 +1,346 @@
+.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/cons
+.B /dev/consctl
+.B /dev/cputime
+.B /dev/drivers
+.B /dev/hostdomain
+.B /dev/hostowner
+.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 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 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 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 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 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 .
+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 authsrv (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 .