cons 9.1 KB

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