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/consctl
  12 .B /dev/cputime
  13 .B /dev/drivers
  14 .B /dev/hostdomain
  15 .B /dev/hostowner
  16 .B /dev/kmesg
  17 .B /dev/kprint
  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/swap
  26 .B /dev/sysname
  27 .B /dev/sysstat
  28 .B /dev/time
  29 .B /dev/user
  30 .B /dev/zero
  31 .fi
  32 .SH DESCRIPTION
  33 The console device serves a one-level directory
  34 giving access to the console and
  35 miscellaneous information.
  36 .PP
  37 Reading the
  38 .B cons
  39 file returns characters typed on the keyboard.
  40 Normally, characters are buffered to enable erase and kill processing.
  41 A control-U,
  42 .LR ^U ,
  43 typed at the keyboard
  44 .I kills
  45 the current input line (removes all characters
  46 from the buffer of characters
  47 not yet read via
  48 .BR cons ),
  49 and a backspace
  50 .I erases
  51 the previous non-kill, non-erase character from the input buffer.
  52 Killing and erasing only delete characters back to, but not including,
  53 the last newline.
  54 Characters typed at the keyboard actually produce 16-bit runes (see
  55 .IR utf (6)),
  56 but the runes are translated into the variable-length
  57 .SM UTF
  58 encoding (see
  59 .IR utf (6))
  60 before putting them into the buffer.
  61 A
  62 .IR read (2)
  63 of length greater than zero causes the process to wait until a
  64 newline or a
  65 .L ^D
  66 ends the buffer, and then returns as much of the buffer as the argument
  67 to
  68 .B read
  69 allows, but only up to one complete line.
  70 A terminating
  71 .L ^D
  72 is not put into the buffer.
  73 If part of the line remains, the next
  74 .B read
  75 will return bytes from that remainder and not part of any new line
  76 that has been typed since.
  77 .PP
  78 If
  79 the string
  80 .B rawon
  81 has been written to the
  82 .B consctl
  83 file and the file is still open,
  84 .B cons
  85 is in
  86 .IR "raw mode" :
  87 characters are not echoed as they are typed,
  88 backspace,
  89 .L ^U
  90 and
  91 .L ^D
  92 are not treated specially,
  93 and characters are available to
  94 .I read
  95 as soon as they are typed.
  96 Ordinary mode is reentered when
  97 .B rawoff
  98 is written to
  99 .B consctl
 100 or this file is closed.
 101 .PP
 102 A
 103 .I write
 104 (see
 105 .IR read (2))
 106 to
 107 .B cons
 108 causes the characters to be printed on the console screen.
 109 .PP
 110 The
 111 .B osversion
 112 file contains a textual representation of the operating system's version and parameters.
 113 At the moment, it contains one field: the 9P protocol version, currently
 114 .BR 2000 .
 115 .PP
 116 The
 117 .B config
 118 file contains a copy of the kernel configuration file used to build the kernel.
 119 .PP
 120 The
 121 .B kmesg
 122 file holds the last 16 kilobytes of output written to the console
 123 by the kernel's print statements or by processes writing to
 124 .BR /dev/cons .
 125 It is useful for retrieving boot messages once the boot
 126 process is over.
 127 .PP
 128 The
 129 .B kprint
 130 file may be read to receive a copy of the data written
 131 to the console by the kernel's print statements or by processes
 132 writing to
 133 .BR /dev/cons .
 134 Only data written after the file is opened is available.
 135 If the machine's console is a serial line, the data is sent both to the
 136 console and to
 137 .BR kprint ;
 138 if its console is a graphics screen, the data is sent either to the
 139 display or to
 140 .BR kprint ,
 141 but not both.
 142 (It is advisable not to open
 143 .B kprint
 144 on terminals until you have started
 145 .IR rio (1).)
 146 .PP
 147 The
 148 .B null
 149 file throws away anything written to it
 150 and always returns zero when read.
 151 .PP
 152 The
 153 .B zero
 154 file is a read-only file that produces an infinite stream of zero-valued bytes when read.
 155 .PP
 156 The
 157 .B drivers
 158 file contains, one per line, a listing of the drivers configured in the kernel, in the format
 159 .IP
 160 .EX
 161 #c cons
 162 .EE
 163 .PP
 164 The
 165 .B hostdomain
 166 file contains the name of the authentication domain that
 167 this host belongs to; see
 168 .IR authsrv (6).
 169 Only the user named in
 170 .B /dev/hostowner
 171 may write this.
 172 .PP
 173 The
 174 .B hostowner
 175 file contains the name of the user that owns the console device files.
 176 The hostowner also has group permissions for any local devices.
 177 .PP
 178 Reads from
 179 .B random
 180 return a stream of random numbers.  The numbers are
 181 generated by a low priority kernel process that loops
 182 incrementing a variable.  Each clock tick the variable
 183 is sampled and, if it has changed sufficiently, the last
 184 few bits are appended to a buffer.  This process is inefficient
 185 at best producing at most a few hundred bits a second.
 186 Therefore,
 187 .B random
 188 should be treated as a seed to
 189 pseudo-random number generators which can produce a faster
 190 rate stream.
 191 .PP
 192 Writing the string
 193 .B reboot
 194 to
 195 .B reboot
 196 causes the system to shutdown and, if
 197 possible, restart.
 198 Writing the string
 199 .B reboot
 200 .I kernelpath
 201 loads the named kernel image and restarts,
 202 preserving the kernel configuration in
 203 .BR #ec ,
 204 except that the
 205 .B bootfile
 206 variable is set to
 207 .IR kernelpath .
 208 Only the host
 209 owner has the ability to open this file.
 210 .PP
 211 .B Bintime
 212 is a binary interface that provides
 213 the same information as
 214 .B time
 215 .RI ( q.v. ),
 216 in binary form,
 217 and also controls clock frequency and clock trim.
 218 All integers read or written from
 219 .B bintime
 220 are in big endian order.
 221 Unlike the other files, reads and writes do not affect
 222 the offset.  Therefore, there is no need for a seek
 223 back to zero between subsequent accesses.
 224 A read of
 225 .B bintime
 226 returns 24 bytes, three 8 byte numbers, representing nanoseconds
 227 since start of epoch, clock ticks, and clock frequency.
 228 .PP
 229 A write to
 230 .B bintime
 231 is a message with one of 3 formats:
 232 .IP "\f5n\fP<8-byte \f2time\fP>" 1.2i
 233 set the nanoseconds since epoch to the given
 234 .IR time .
 235 .IP "\f5d\fP<8-byte \f2delta\fP><4-byte \f2period\fP>" 1.2i
 236 trim the nanoseconds since epoch by
 237 .I delta
 238 over the next
 239 .I period
 240 seconds.
 241 .IP "\f5f\fP<8-byte \f2freq\fP>" 1.2i
 242 Set the frequency for interpreting clock ticks to be
 243 .I freq
 244 ticks per second.
 245 .PP
 246 The rest of the files contain (mostly) read-only strings.
 247 Each string has a fixed length: a
 248 .IR read (2)
 249 of more than that gives a result of that fixed length (the result does not
 250 include a terminating zero byte);
 251 a
 252 .I read
 253 of less than that length leaves the file offset so the
 254 rest of the string (but no more) will be read the next time.
 255 To reread the file without closing it,
 256 .I seek
 257 must be used to reset the offset.
 258 When the file contains numeric data
 259 each number is formatted in decimal.
 260 If the binary number fits in 32 bits, it is formatted as an
 261 11 digit decimal number with
 262 leading blanks and one trailing blank; totaling 12 bytes.
 263 Otherwise, it
 264 is formatted as 21 digit decimal numbers with leading blanks and one
 265 trailing blank; totaling 22 bytes.
 266 .PP
 267 The
 268 .B cputime
 269 file holds six 32-bit numbers, containing the time in milliseconds
 270 that the current process has spent in user mode, system calls,
 271 real elapsed time, and then the time spent, by exited children and their descendants,
 272 in user mode, system calls, and real elapsed time.
 273 .PP
 274 The
 275 .B time
 276 file holds one 32-bit number representing the seconds since start of epoch
 277 and three 64-bit numbers, representing nanoseconds since
 278 start of epoch, clock ticks, and clock frequency.
 279 .PP
 280 A write of a decimal number to
 281 .B time
 282 will set the seconds since epoch.
 283 .PP
 284 The
 285 .B sysname
 286 file holds the textual name of the machine, e.g.
 287 .BR kremvax ,
 288 if known.
 289 .PP
 290 The
 291 .B sysstat
 292 file holds 10 numbers:
 293 processor number, context switches, interrupts, system calls, page faults,
 294 TLB faults, TLB purges, load average, idle time and time spent servicing interrupts.
 295 The load average is in units of milli-CPUs and is decayed over time;
 296 idle time and interrupt time are percentage units;
 297 the others are total counts from boot time.
 298 If the machine is a multiprocessor,
 299 .B sysstat
 300 holds one line per processor.
 301 Writing anything to
 302 .B sysstat
 303 resets all of the counts on all processors.
 304 .PP
 305 The
 306 .B swap
 307 device holds a text block giving memory usage statistics:
 308 .IP
 309 .EX
 310 \fIn\fP memory
 311 \fIn\fP pagesize
 312 \fIn\fP kernel
 313 \fIn\fP/\fIm\fP user
 314 \fIn\fP/\fIm\fP swap
 315 \fIn\fP/\fIm\fP kernel malloc
 316 \fIn\fP/\fIm\fP kernel draw
 317 .EE
 318 .PP
 319 These are total memory (bytes), system page size (bytes),
 320 kernel memory (pages), user memory (pages), swap space (pages),
 321 kernel malloced data (bytes), and kernel graphics data (bytes).
 322 The expression
 323 .IR n / m
 324 indicates
 325 .I n
 326 used out of
 327 .I m
 328 available.
 329 These numbers are not blank padded.
 330 .PP
 331 To turn on swapping, write to
 332 .B swap
 333 the textual file descriptor number of a file or device on which to swap.
 334 See
 335 .IR swap (8).
 336 .PP
 337 Reads and writes to
 338 .IR mordor
 339 will inevitably cause the front to fall off.
 340 .PP
 341 The other files served by the
 342 .I cons
 343 device are all single numbers:
 344 .TP 10
 345 .B pgrpid
 346 process group number
 347 .TP
 348 .B pid
 349 process number
 350 .TP
 351 .B ppid
 352 parent's process number
 353 .SH SEE ALSO
 354 .IR draw (3),
 355 .IR keyboard (6),
 356 .IR authsrv (6),
 357 .IR utf (6),
 358 .IR swap (8)
 359 .SH SOURCE
 360 .B /sys/src/9/port/devcons.c
 361 .SH BUGS
 362 For debugging, two control-T's followed by a letter
 363 generate console output and manage debugging:
 364 .L ^T^Td
 365 toggles whether the console debugger will be run if the system fails.
 366 .L ^T^TD
 367 starts the console debugger immediately.
 368 .L ^T^Tk
 369 kills the largest process; use with care.
 370 .L ^T^Tp
 371 prints data about processes.
 372 .L ^T^Tq
 373 prints the run queue for processor 0.
 374 .L ^T^Ts
 375 prints the kernel stack.
 376 .L ^T^Tx
 377 prints data about kernel memory allocation.
 378 .PP
 379 The system can be rebooted by typing
 380 .LR ^T^Tr .