CONS(3)                                                   CONS(3)

     NAME
          cons - console, clocks, process/process group ids, user,
          null, klog, stats, lights, noise, sysstat, hz, swap, crypt,
          chal, key

     SYNOPSIS
          bind #c /dev

          /dev/chal
          /dev/clock
          /dev/cons
          /dev/consctl
          /dev/cputime
          /dev/crypt
          /dev/hz
          /dev/key
          /dev/klog
          /dev/lights
          /dev/msec
          /dev/noise
          /dev/null
          /dev/pgrpid
          /dev/pid
          /dev/ppid
          /dev/swap
          /dev/sysname
          /dev/sysstat
          /dev/time
          /dev/user

     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 16-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.
          A terminating `^D' is not put into the buffer.  If part of

     Page 1                       Plan 9             (printed 12/2/22)

     CONS(3)                                                   CONS(3)

          the line remains, the next read will return characters 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 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 null file throws away anything written to it and always
          returns zero bytes when read.

          The klog file contains the tail of messages written by ker-
          nel logging statements.

          Writing a number (as plain text) to the lights device
          directs any lights that are available to turn on and off.
          The bits of the number are mapped to the lights in a
          processor-dependent way.

          Writing two blank- or tab- separated numbers to the noise
          device causes the machine to make a tone, if possible.  The
          first number is the frequency, in Hertz, and the second is
          the duration, in milliseconds.

          The crypt file performs DES encryption. To encrypt data,
          first a character `E' (0x45) is written to the file, and
          then the data, which must be at least 8 bytes long.  Data
          longer that 127 bytes is truncated.  Data is encrypted with
          the same algorithm used in encrypt(2). The encrypted data
          can then be read from the file.  A similar procedure is used
          to decrypt data, except an ASCII `D' (0x44) is written to
          the file before the data.

          The key file is used to set the DES key used for encryption;
          the key is shared within a process group (see auth(6)).

          The chal file is used for authenticated setting of the user
          name.  When read, it returns an encrypted challenge string
          to be used for authenticating the user's identity.  When
          written with the appropriate string, the user name and
          encryption key are set.  The format of the strings is docu-
          mented in auth(6).

          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 2                       Plan 9             (printed 12/2/22)

     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 format-
          ted in decimal as an 11-digit number with leading blanks and
          one trailing blank: twelve bytes total.

          The user file contains the name of the user associated with
          the current process.

          The cputime file holds 6 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 clock file holds two numbers: the number of clock ticks
          since booting followed by the number of clock ticks in a
          second.

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

          The sysstat file holds 8 numbers: processor number, context
          switches, interrupts, system calls, page faults, tlb faults,
          tlb purges, and load average.  If the machine is a multipro-
          cessor, sysstat holds one line per processor.  Writing any-
          thing to sysstat resets all of the counts on all processors.

          The swap device holds a string of the form

               m1/m2 memory s1/s2 swap

          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 swap the textual file descriptor 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:

          hz        frequency of the system clock

          msec      number of milliseconds since booting

          pgrpid    process group number

          pid       process number

          ppid      parent's process number

     Page 3                       Plan 9             (printed 12/2/22)

     CONS(3)                                                   CONS(3)

          time      number of seconds since the epoch 00:00:00 GMT,
                    Jan. 1, 1970.  (Can be written once, to set at
                    boot time.)

     SEE ALSO
          bit(3), keyboard(6), auth(6), utf(6)

     BUGS
          For debugging, two control-T's followed by a letter generate
          console output: `^T^Tp' prints data about processes, `^T^Tq'
          prints data about streams, `^T^Tm' prints data about the
          mount device, `^T^Tb' prints data about the bitblt device,
          and `^T^Tx' prints date about kernel memory allocation.

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

     Page 4                       Plan 9             (printed 12/2/22)