CONS(3)                                                   CONS(3)

     NAME
          cons - console, clocks, process/process group ids, user,
          null, reboot, etc.

     SYNOPSIS
          bind #c /dev

          /dev/bintime
          /dev/config
          /dev/cons
          /dev/consctl
          /dev/cputime
          /dev/drivers
          /dev/hostdomain
          /dev/hostowner
          /dev/kmesg
          /dev/kprint
          /dev/null
          /dev/osversion
          /dev/pgrpid
          /dev/pid
          /dev/ppid
          /dev/random
          /dev/reboot
          /dev/swap
          /dev/sysname
          /dev/sysstat
          /dev/time
          /dev/user
          /dev/zero

     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 21-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.

     Page 1                       Plan 9            (printed 10/31/24)

     CONS(3)                                                   CONS(3)

          A terminating `^D' is not put into the buffer.  If part of
          the line remains, the next read will return bytes 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, `^U' 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 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
          2000.

          The config file contains a copy of the kernel configuration
          file used to build the kernel.

          The kmesg file holds the last 16 kilobytes of output written
          to the console by the kernel's print statements or by pro-
          cesses writing to /dev/cons.  It is useful for retrieving
          boot messages once the boot process is over.

          The 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 /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 kprint; if its console is a graphics screen, the data is
          sent either to the display or to kprint, but not both.  (It
          is advisable not to open kprint on terminals until you have
          started rio(1).)

          The null file throws away anything written to it and always
          returns zero when read.

          The zero file is a read-only file that produces an infinite
          stream of zero-valued bytes when read.

          The drivers file contains, one per line, a listing of the
          drivers configured in the kernel, in the format

               #c cons

          The hostdomain file contains the name of the authentication
          domain that this host belongs to; see authsrv(6). Only the
          user named in /dev/hostowner may write this.

     Page 2                       Plan 9            (printed 10/31/24)

     CONS(3)                                                   CONS(3)

          The hostowner file contains the name of the user that owns
          the console device files.  The hostowner also has group per-
          missions for any local devices.

          Reads from 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, random should be treated as a seed to pseudo-
          random number generators which can produce a faster rate
          stream.

          Writing the string reboot to reboot causes the system to
          shutdown and, if possible, restart.  Writing the string
          reboot kernelpath loads the named kernel image and restarts,
          preserving the kernel configuration in #ec, except that the
          bootfile variable is set to kernelpath. Only the host owner
          has the ability to open this file.  The named kernel may be
          a Plan 9 executable or a 32-bit or 64-bit ELF executable.
          On some architectures (e.g., mips), it may also be a Plan 9
          boot image.

          Bintime is a binary interface that provides the same infor-
          mation as time (q.v.), in binary form, and also controls
          clock frequency and clock trim.  All integers read or writ-
          ten from bintime are in big endian order.  Unlike the other
          files, reads and writes do not affect the offset.  There-
          fore, there is no need for a seek back to zero between sub-
          sequent accesses.  A read of bintime returns 24 bytes, three
          8 byte numbers, representing nanoseconds since start of
          epoch, clock ticks, and clock frequency.

          A write to bintime is a message with one of 3 formats:

          n<8-byte time>
                      set the nanoseconds since epoch to the given
                      time.

          d<8-byte delta><4-byte period>
                      trim the nanoseconds since epoch by delta over
                      the next period seconds.

          f<8-byte freq>
                      Set the frequency for interpreting clock ticks
                      to be freq ticks per second.

        Statistics and Dynamic Status
          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 3                       Plan 9            (printed 10/31/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 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.

          The 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.

          The time file holds one 32-bit number representing the sec-
          onds since start of epoch and three 64-bit numbers, repre-
          senting nanoseconds since start of epoch, clock ticks, and
          clock frequency.

          A write of a decimal number to time will set the seconds
          since epoch.

          The sysname file holds the textual name of the machine, e.g.
          kremvax, if known.

          The 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 per-
          centage units; the others are total counts from boot time.
          If the machine is a multiprocessor, sysstat holds one line
          per processor.  Writing anything to sysstat resets all of
          the counts on all processors.

          The swap device holds a text block giving memory usage
          statistics:

               n memory
               n pagesize
               n kernel
               n/m user
               n/m swap
               n/m kernel malloc
               n/m kernel draw

          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

     Page 4                       Plan 9            (printed 10/31/24)

     CONS(3)                                                   CONS(3)

          data (bytes).  The expression n/m indicates n used out of m
          available.  These numbers are not blank padded.

          To turn on swapping, write to swap the textual file descrip-
          tor 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:

          pgrpid    process group number

          pid       process number

          ppid      parent's process number

     SEE ALSO
          draw(3), keyboard(6), authsrv(6), utf(6), swap(8)

     SOURCE
          /sys/src/9/port/devcons.c

     BUGS
          For debugging, two control-T's followed by a letter generate
          console output and manage debugging: `^T^Td' toggles whether
          the console debugger will be run if the system fails.
          `^T^TD' starts the console debugger immediately.  `^T^Tk'
          kills the largest process; use with care.  `^T^Tp' prints
          data about processes.  `^T^Tq' prints the run queue for pro-
          cessor 0.  `^T^Ts' prints the kernel stack.  `^T^Tx' prints
          data about kernel memory allocation.

          The system can be rebooted by typing `^T^Tr'.

     Page 5                       Plan 9            (printed 10/31/24)