unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (plan9)
Page:
Section:
Apropos / Subsearch:
optional field

CONS(3)                    Library Functions Manual                    CONS(3)



NAME
       cons  -  console,  clocks, process/process group ids, user, null, klog,
       stats, lights, noise, sysstat, hz, swap,  key,  hostowner,  hostdomain,
       authenticate, authcheck, authenticator

SYNOPSIS
       bind #c /dev

       /dev/authcheck
       /dev/authenticate
       /dev/authenticator
       /dev/clock
       /dev/cons
       /dev/consctl
       /dev/cputime
       /dev/hostdomain
       /dev/hostowner
       /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  keyboard.   Nor-
       mally,  characters are buffered to enable erase and kill processing.  A
       control-U, typed at the keyboard 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 trans-
       lated 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 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 is not put into the buffer.  If  part
       of  the line remains, the next read will return bytes from that remain-
       der 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 are not treated specially, and characters  are
       available  to  read  as soon as they are typed.  Ordinary mode is reen-
       tered 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  kernel  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  fre-
       quency, in Hertz, and the second is the duration, in milliseconds.

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

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

       The  key  file  is  used  to set the DES key used for encryption.  Each
       machine has one key.  Only the user named in /dev/hostowner  may  write
       this.

       The  authenticate file is used to authenticate new users to the kernel;
       see auth(6).  After an open, the first read returns  a  ticket  request
       message of the following form:
            char num;
            char authid[28];
            char authdom[48];
            char chal[8];
            char hostid[28];
            char uid[28];
       Here  num  is  1,  authid and hostid are the contents of hostowner, and
       authdom is the contents of hostdomain.  Chal is an 8 byte random  chal-
       lenge  created  by  the  kernel.   A subsequent write of a valid ticket
       encrypted with the key contained in key changes the user  name  of  the
       writing  process  to the value of suid in the ticket.  The ticket is of
       the form:
            char num;
            char chal[8];
            char cuid[28];
            char suid[28];
            char noncekey[7];
       The ticket is valid if num is 64 and chal matches the challenge in  the
       ticket  request.  Writing an invalid ticket generates an error.  A read
       following a successful write yields an  authenticator  message  of  the
       form:
            char num;
            char chal[8];
            char id[4];
       The authenticator is encrypted in noncekey from the ticket.  Num is 66,
       id[0-4] are 0, and chal matches the challenge in  the  original  ticket
       request.

       The  authenticator  file  is  used  to generate an authenticator from a
       ticket.  One writes a ticket encrypted with the key contained  in  key,
       followed,  optionally,  by  a 4-byte id; a missing id defaults to zero.
       If the client uid matches the current user, a subsequent read yields an
       authenticator for that ticket with the given id.

       The authcheck file is used to match authenticators to tickets.  A write
       of an authenticator appended to the end of a  ticket  succeeds  if  the
       ticket  is encrypted with the key contained in key, the ticket's num is
       65, the authenticator is encrypted  with  the  ticket's  noncekey,  the
       authenticator's  and  ticket's chal's match, the authenticator's num is
       66, and the authenticator's id is 0.  Alternatively, the write may con-
       sist  of  ticket,  authenticator, chal, and id, in which case the given
       chal and id must match those of the authenticator.

       The user file contains the name of the user associated with the current
       process.   Any  process can change to user none by writing none to this
       file.

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

       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 boot-
       ing 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.   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,  sysstat  holds one line per processor.  Writing
       anything 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 num-
       ber 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

       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), swap(8)

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

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

       The system can be rebooted by typing



                                                                       CONS(3)