1
0

cons 8.8 KB

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