![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cons CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Plan 9 NeXT] / lucent / sys / man / 3|
Return to cons CVS log | Up to [Plan 9 NeXT] / lucent / sys / man / 3 |
1.1 root 1: .TH CONS 3
2: .SH NAME
3: cons \- console, clocks, process/process group ids, user, null, klog, stats, lights, noise, sysstat, hz, swap, key, hostowner, hostdomain, authenticate, authcheck, authenticator
4: .SH SYNOPSIS
5: .nf
6: .B bind #c /dev
7:
8: .B /dev/authcheck
9: .B /dev/authenticate
10: .B /dev/authenticator
11: .B /dev/clock
12: .B /dev/cons
13: .B /dev/consctl
14: .B /dev/cputime
15: .B /dev/hostdomain
16: .B /dev/hostowner
17: .B /dev/hz
18: .B /dev/key
19: .B /dev/klog
20: .B /dev/lights
21: .B /dev/msec
22: .B /dev/noise
23: .B /dev/null
24: .B /dev/pgrpid
25: .B /dev/pid
26: .B /dev/ppid
27: .B /dev/swap
28: .B /dev/sysname
29: .B /dev/sysstat
30: .B /dev/time
31: .B /dev/user
32: .fi
33: .SH DESCRIPTION
34: The console device serves a one-level directory
35: giving access to the console and
36: miscellaneous information.
37: .PP
38: Reading the
39: .B cons
40: file returns characters typed on the keyboard.
41: Normally, characters are buffered to enable erase and kill processing.
42: A control-U,
43: .LR ^U ,
44: typed at the keyboard
45: .I kills
46: the current input line (removes all characters
47: from the buffer of characters
48: not yet read via
49: .BR cons ),
50: and a backspace
51: .I erases
52: the previous non-kill, non-erase character from the input buffer.
53: Killing and erasing only delete characters back to, but not including,
54: the last newline.
55: Characters typed at the keyboard actually produce 16-bit runes (see
56: .IR utf (6)),
57: but the runes are translated into the variable-length
58: .SM UTF
59: encoding (see
60: .IR utf (6))
61: before putting them into the buffer.
62: A
63: .IR read (2)
64: of length greater than zero causes the process to wait until a
65: newline or a
66: .L ^D
67: ends the buffer, and then returns as much of the buffer as the argument
68: to
69: .B read
70: allows, but only up to one complete line.
71: A terminating
72: .L ^D
73: is not put into the buffer.
74: If part of the line remains, the next
75: .B read
76: will return bytes from that remainder and not part of any new line
77: that has been typed since.
78: .PP
79: If
80: the string
81: .B rawon
82: has been written to the
83: .B consctl
84: file and the file is still open,
85: .B cons
86: is in
87: .IR "raw mode" :
88: characters are not echoed as they are typed,
89: backspace 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 null
111: file throws away anything written to it
112: and always returns zero bytes when read.
113: .PP
114: The
115: .B klog
116: file contains the tail of messages written by kernel logging statements.
117: .PP
118: Writing a number (as plain text) to the
119: .B lights
120: device directs any lights that are available to turn on and off.
121: The bits of the number are mapped to the lights in a processor-dependent way.
122: .PP
123: Writing two blank- or tab-separated numbers to the
124: .B noise
125: device causes the machine to make a tone, if possible.
126: The first number is the frequency, in Hertz, and the second is
127: the duration, in milliseconds.
128: .PP
129: The
130: .B hostdomain
131: file contains the name of the authentication domain that
132: this host belongs to; see
133: .IR auth (6).
134: Only the user named in
135: .B /dev/hostowner
136: may write this.
137: .PP
138: The
139: .B hostowner
140: file contains the name of the user that owns the console device files.
141: The hostowner also has group permissions for any local devices.
142: .PP
143: The
144: .B key
145: file is used to set the DES key used for encryption.
146: Each machine has one key.
147: Only the user named in
148: .B /dev/hostowner
149: may write this.
150: .PP
151: The
152: .B authenticate
153: file is used to authenticate new users to the kernel; see
154: .IR auth (6).
155: After an open, the first read returns a ticket request message
156: of the following form:
157: .EX
158: char num;
159: char authid[28];
160: char authdom[48];
161: char chal[8];
162: char hostid[28];
163: char uid[28];
164: .EE
165: Here
166: .I num
167: is 1,
168: .I authid
169: and
170: .I hostid
171: are the contents of
172: .BR hostowner ,
173: and
174: .I authdom
175: is the contents of
176: .BR hostdomain .
177: .I Chal
178: is an 8 byte random challenge created by the kernel.
179: A subsequent write of a valid ticket encrypted with the key contained in
180: .B key
181: changes the user name of the writing process to the value of
182: .I suid
183: in the ticket.
184: The ticket is of the form:
185: .EX
186: char num;
187: char chal[8];
188: char cuid[28];
189: char suid[28];
190: char noncekey[7];
191: .EE
192: The ticket is valid if
193: .I num
194: is 64 and
195: .I chal
196: matches the challenge in the ticket request.
197: Writing an invalid ticket generates an error.
198: A read following a successful write yields an authenticator
199: message of the form:
200: .EX
201: char num;
202: char chal[8];
203: char id[4];
204: .EE
205: The authenticator is encrypted in
206: .I noncekey
207: from the ticket.
208: .I Num
209: is 66,
210: .IR id [0-4]
211: are 0,
212: and
213: .I chal
214: matches the challenge in the original ticket request.
215: .PP
216: The
217: .B authenticator
218: file is used to generate an authenticator from a ticket.
219: One writes a ticket encrypted with the key contained in
220: .BR key ,
221: followed, optionally, by a 4-byte
222: .IR id ;
223: a missing
224: .I id
225: defaults to zero.
226: If the client uid matches the current user, a subsequent read yields
227: an authenticator for that ticket with the given
228: .IR id .
229: .PP
230: The
231: .B authcheck
232: file is used to match authenticators to tickets.
233: A write of an authenticator appended to the end of a ticket
234: succeeds if the ticket is encrypted with
235: the key contained in
236: .BR key ,
237: the ticket's
238: .I num
239: is 65,
240: the authenticator is encrypted with the ticket's
241: .BR noncekey ,
242: the authenticator's and ticket's
243: .IR chal 's
244: match, the authenticator's
245: .I num
246: is 66, and the authenticator's
247: .I id
248: is 0. Alternatively, the write may consist of ticket, authenticator,
249: .IR chal ,
250: and
251: .IR id ,
252: in which case the given
253: .I chal
254: and
255: .I id
256: must match those of the authenticator.
257: .PP
258: The
259: .B user
260: file contains the name of the user associated with the current process.
261: Any process can change to user
262: .B none
263: by writing
264: .B none
265: to this file.
266: .PP
267: The rest of the files contain (mostly) read-only strings.
268: Each string has a fixed length: a
269: .IR read (2)
270: of more than that gives a result of that fixed length (the result does not
271: include a terminating zero byte);
272: a
273: .I read
274: of less than that length leaves the file offset so the
275: rest of the string (but no more) will be read the next time.
276: To reread the file without closing it,
277: .I seek
278: must be used to reset the offset.
279: When the file contains numeric data, each number is formatted
280: in decimal as an 11-digit number with leading blanks and
281: one trailing blank: twelve bytes total.
282: .PP
283: The
284: .B cputime
285: file holds 6 numbers, containing the time in milliseconds
286: that the current process has spent in user mode, system calls,
287: real elapsed time, and then the time spent, by exited children and their descendants,
288: in user mode, system calls, and real elapsed time.
289: .PP
290: The
291: .B clock
292: file holds two numbers: the number of
293: clock ticks since booting followed by the number of clock ticks
294: in a second.
295: .PP
296: The
297: .B sysname
298: file holds the textual name of the machine, e.g.
299: .BR kremvax ,
300: if known.
301: .PP
302: The
303: .B sysstat
304: file holds 8 numbers:
305: processor number, context switches, interrupts, system calls, page faults,
306: tlb faults, tlb purges, and load average.
307: The load average is in units of milli-CPUs and is decayed over time;
308: the others are total counts from boot time.
309: If the machine is a multiprocessor,
310: .B sysstat
311: holds one line per processor.
312: Writing anything to
313: .B sysstat
314: resets all of the counts on all processors.
315: .PP
316: The
317: .B swap
318: device holds a string of the form
319: .IP
320: .IB m1 / m2
321: .B memory
322: .IB s1 / s2
323: .B swap
324: .PP
325: These give, for each of
326: internal memory and the swapping area,
327: the number of pages used and the total available.
328: These numbers are not blank padded.
329: To turn on swapping, write to
330: .B swap
331: the textual file descriptor number of a file or device on which to swap.
332: See
333: .IR swap (8).
334: .PP
335: The other files served by the
336: .I cons
337: device are all single numbers:
338: .TP 10
339: .B hz
340: frequency of the system clock
341: .TP
342: .B msec
343: number of milliseconds since booting
344: .TP
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: .TP
354: .B time
355: number of seconds since the epoch 00:00:00 GMT, Jan. 1, 1970.
356: (Can be written once, to set at boot time.)
357: .SH SEE ALSO
358: .IR bit (3),
359: .IR keyboard (6),
360: .IR auth (6),
361: .IR utf (6),
362: .IR swap (8)
363: .SH SOURCE
364: .B /sys/src/9/port/devcons.c
365: .SH BUGS
366: For debugging, two control-T's followed by a letter
367: generate console output:
368: .L ^T^Tp
369: prints data about processes,
370: .L ^T^Tq
371: prints data about streams,
372: .L ^T^Tm
373: prints data about the mount device,
374: .L ^T^Tb
375: prints data about the bitblt device, and
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 .
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.