cons 8.4 KB

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