ref: 578af37678b2ea16e29d950cbc352823cd2491ab
dir: /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/mordor .B /dev/null .B /dev/osversion .B /dev/pid .B /dev/ppid .B /dev/random .B /dev/reboot .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 available kernel drivers, in the format .IP .EX #c cons .EE .PP Each process name group (see .IR fork (2)) maintains a mask of allowed drivers. A process can modify that mask through writes to the .B drivers file. Messages are in the format of: .IP .EX chdev \f2op\fP \f2devmask\fP .EE .PP .I Devmask is a string of driver characters. .I Op specifies how .I devmask is interpreted. .I Op is one of: .TP .B & Permit access to just the drivers specified in .IR devmask . .TP .B &~ Permit access to all but the drivers specified in .IR devmask . .TP .B ~ Remove access to all devices. .I Devmask is ignored. .PP Access may only be removed. No .I op permits a process to regain access to a driver once it has been removed. Removing access to .IR mnt (3) additionally prevents new mounts into the current namespace. The following removes access to all drivers except .IR draw (3), .IR cons (3), and .IR fs (3): .IP .EX chdev & ick .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 bytes produced by the kernels cryptographic random number generator. The rate at which data can be read depends on the implementation and can vary from hundreds of megabytes to just 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 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 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