sys/man/3/cons

   1 .TH CONS 3
   2 .SH NAME
   3 cons \- console, clocks, process/process group ids, user, null, reboot, etc.
   4 .SH SYNOPSIS
   5 .nf
   6 .B bind #c /dev
   7
   8 .B /dev/bintime
   9 .B /dev/config
  10 .B /dev/cons
  11 .B /dev/cputime
  12 .B /dev/drivers
  13 .B /dev/hostdomain
  14 .B /dev/hostowner
  15 .B /dev/kmesg
  16 .B /dev/kprint
  17 .B /dev/mordor
  18 .B /dev/null
  19 .B /dev/osversion
  20 .B /dev/pgrpid
  21 .B /dev/pid
  22 .B /dev/ppid
  23 .B /dev/random
  24 .B /dev/reboot
  25 .B /dev/sysname
  26 .B /dev/sysstat
  27 .B /dev/time
  28 .B /dev/user
  29 .B /dev/zero
  30 .fi
  31 .SH DESCRIPTION
  32 The console device serves a one-level directory
  33 giving access to the console screen and
  34 miscellaneous information.
  35 .PP
  36 A
  37 .I write
  38 (see
  39 .IR read (2))
  40 to
  41 .B cons
  42 causes the characters to be printed on the console screen. Console
  43 input is handled by a different program (see
  44 .IR kbdfs (8)).
  45 .PP
  46 The
  47 .B osversion
  48 file contains a textual representation of the operating system's version and parameters.
  49 At the moment, it contains one field: the 9P protocol version, currently
  50 .BR 2000 .
  51 .PP
  52 The
  53 .B config
  54 file contains a copy of the kernel configuration file used to build the kernel.
  55 .PP
  56 The
  57 .B kmesg
  58 file holds the last 16 kilobytes of output written to the console
  59 by the kernel's print statements or by processes writing to
  60 .BR /dev/cons .
  61 It is useful for retrieving boot messages once the boot
  62 process is over.
  63 .PP
  64 The
  65 .B kprint
  66 file may be read to receive a copy of the data written
  67 to the console by the kernel's print statements or by processes
  68 writing to
  69 .BR /dev/cons .
  70 Only data written after the file is opened is available.
  71 If the machine's console is a serial line, the data is sent both to the
  72 console and to
  73 .BR kprint ;
  74 if its console is a graphics screen, the data is sent either to the
  75 display or to
  76 .BR kprint ,
  77 but not both.
  78 (It is advisable not to open
  79 .B kprint
  80 on terminals until you have started
  81 .IR rio (1).)
  82 .PP
  83 The
  84 .B null
  85 file throws away anything written to it
  86 and always returns zero when read.
  87 .PP
  88 The
  89 .B zero
  90 file is a read-only file that produces an infinite stream of zero-valued bytes when read.
  91 .PP
  92 The
  93 .B drivers
  94 file contains, one per line, a listing of the drivers configured in the kernel, in the format
  95 .IP
  96 .EX
  97 #c cons
  98 .EE
  99 .PP
 100 The
 101 .B hostdomain
 102 file contains the name of the authentication domain that
 103 this host belongs to; see
 104 .IR authsrv (6).
 105 Only the user named in
 106 .B /dev/hostowner
 107 may write this.
 108 .PP
 109 The
 110 .B hostowner
 111 file contains the name of the user that owns the console device files.
 112 The hostowner also has group permissions for any local devices.
 113 .PP
 114 Reads from
 115 .B random
 116 return a stream of random bytes produced by the kernels cryptographic
 117 random number generator. The rate at which data can be read depends on
 118 the implementation and can vary from hundreds of megabytes to just
 119 a few hundred bits a second. Therefore,
 120 .B random
 121 should be treated as a seed to
 122 pseudo-random number generators which can produce a faster
 123 rate stream.
 124 .PP
 125 Writing the string
 126 .B reboot
 127 to
 128 .B reboot
 129 causes the system to shutdown and, if
 130 possible, restart.
 131 Writing the string
 132 .B reboot
 133 .I kernelpath
 134 loads the named kernel image and restarts,
 135 preserving the kernel configuration in
 136 .BR #ec ,
 137 except that the
 138 .B bootfile
 139 variable is set to
 140 .IR kernelpath .
 141 Writing the string
 142 .B rdb
 143 activates the remote kernel debugger (see
 144 .IR rdbfs (4)).
 145 Only the host
 146 owner has the ability to open this file.
 147 .PP
 148 .B Bintime
 149 is a binary interface that provides
 150 the same information as
 151 .B time
 152 .RI ( q.v. ),
 153 in binary form,
 154 and also controls clock frequency and clock trim.
 155 All integers read or written from
 156 .B bintime
 157 are in big endian order.
 158 Unlike the other files, reads and writes do not affect
 159 the offset.  Therefore, there is no need for a seek
 160 back to zero between subsequent accesses.
 161 A read of
 162 .B bintime
 163 returns 24 bytes, three 8 byte numbers, representing nanoseconds
 164 since start of epoch, clock ticks, and clock frequency.
 165 .PP
 166 A write to
 167 .B bintime
 168 is a message with one of 3 formats:
 169 .IP "\f5n\fP<8-byte \f2time\fP>" 1.2i
 170 set the nanoseconds since epoch to the given
 171 .IR time .
 172 .IP "\f5d\fP<8-byte \f2delta\fP><4-byte \f2period\fP>" 1.2i
 173 trim the nanoseconds since epoch by
 174 .I delta
 175 over the next
 176 .I period
 177 seconds.
 178 .IP "\f5f\fP<8-byte \f2freq\fP>" 1.2i
 179 Set the frequency for interpreting clock ticks to be
 180 .I freq
 181 ticks per second.
 182 .PP
 183 The rest of the files contain (mostly) read-only strings.
 184 Each string has a fixed length: a
 185 .IR read (2)
 186 of more than that gives a result of that fixed length (the result does not
 187 include a terminating zero byte);
 188 a
 189 .I read
 190 of less than that length leaves the file offset so the
 191 rest of the string (but no more) will be read the next time.
 192 To reread the file without closing it,
 193 .I seek
 194 must be used to reset the offset.
 195 When the file contains numeric data
 196 each number is formatted in decimal.
 197 If the binary number fits in 32 bits, it is formatted as an
 198 11 digit decimal number with
 199 leading blanks and one trailing blank; totaling 12 bytes.
 200 Otherwise, it
 201 is formatted as 21 digit decimal numbers with leading blanks and one
 202 trailing blank; totaling 22 bytes.
 203 .PP
 204 The
 205 .B cputime
 206 file holds six 32-bit numbers, containing the time in milliseconds
 207 that the current process has spent in user mode, system calls,
 208 real elapsed time, and then the time spent, by exited children and their descendants,
 209 in user mode, system calls, and real elapsed time.
 210 .PP
 211 The
 212 .B time
 213 file holds one 32-bit number representing the seconds since start of epoch
 214 and three 64-bit numbers, representing nanoseconds since
 215 start of epoch, clock ticks, and clock frequency.
 216 .PP
 217 A write of a decimal number to
 218 .B time
 219 will set the seconds since epoch.
 220 .PP
 221 The
 222 .B sysname
 223 file holds the textual name of the machine, e.g.
 224 .BR kremvax ,
 225 if known.
 226 .PP
 227 The
 228 .B sysstat
 229 file holds 10 numbers:
 230 processor number, context switches, interrupts, system calls, page faults,
 231 TLB faults, TLB purges, load average, idle time and time spent servicing interrupts.
 232 The load average is in units of milli-CPUs and is decayed over time;
 233 idle time and interrupt time are percentage units;
 234 the others are total counts from boot time.
 235 If the machine is a multiprocessor,
 236 .B sysstat
 237 holds one line per processor.
 238 Writing anything to
 239 .B sysstat
 240 resets all of the counts on all processors.
 241 .PP
 242 Reads and writes to
 243 .IR mordor
 244 will inevitably cause the front to fall off.
 245 .PP
 246 The other files served by the
 247 .I cons
 248 device are all single numbers:
 249 .TP 10
 250 .B pgrpid
 251 process group number
 252 .TP
 253 .B pid
 254 process number
 255 .TP
 256 .B ppid
 257 parent's process number
 258 .SH SEE ALSO
 259 .IR draw (3),
 260 .IR kbd (3),
 261 .IR kbdfs (8),
 262 .IR keyboard (6),
 263 .IR authsrv (6),
 264 .IR utf (6),
 265 .IR swap (8)
 266 .SH SOURCE
 267 .B /sys/src/9/port/devcons.c