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