Subversion Repositories planix.SVN

.TH CONS 3

.SH NAME

cons \- console, clocks, process/process group ids, user, null, reboot, etc.

.SH SYNOPSIS

.nf

.B bind #c /dev

.B /dev/bintime

.B /dev/config

.B /dev/cons

.B /dev/consctl

.B /dev/cputime

.B /dev/drivers

.B /dev/hostdomain

.B /dev/hostowner

.B /dev/kmesg

.B /dev/kprint

.B /dev/null

.B /dev/osversion

.B /dev/pgrpid

.B /dev/pid

.B /dev/ppid

.B /dev/random

.B /dev/reboot

.B /dev/swap

.B /dev/sysname

.B /dev/sysstat

.B /dev/time

.B /dev/user

.B /dev/zero

.fi

.SH DESCRIPTION

The console device serves a one-level directory

giving access to the console and

miscellaneous information.

.PP

Reading the

.B cons

file returns characters typed on the keyboard.

Normally, characters are buffered to enable erase and kill processing.

A control-U,

.LR ^U ,

typed at the keyboard

.I kills

the current input line (removes all characters

from the buffer of characters

not yet read via

.BR cons ),

and a backspace

.I erases

the previous non-kill, non-erase character from the input buffer.

Killing and erasing only delete characters back to, but not including,

the last newline.

Characters typed at the keyboard actually produce 21-bit runes (see

.IR utf (6)),

but the runes are translated into the variable-length

.SM UTF

encoding (see

.IR utf (6))

before putting them into the buffer.

A

.IR read (2)

of length greater than zero causes the process to wait until a

newline or a

.L ^D

ends the buffer, and then returns as much of the buffer as the argument

to

.B read

allows, but only up to one complete line.

A terminating

.L ^D

is not put into the buffer.

If part of the line remains, the next

.B read

will return bytes from that remainder and not part of any new line

that has been typed since.

.PP

If

the string

.B rawon

has been written to the

.B consctl

file and the file is still open,

.B cons

is in

.IR "raw mode" :

characters are not echoed as they are typed,

backspace,

.L ^U

and

.L ^D

are not treated specially,

and characters are available to

.I read

as soon as they are typed.

Ordinary mode is reentered when

.B rawoff

is written to

.B consctl

or this file is closed.

.PP

A

.I write

(see

.IR read (2))

to

.B cons

causes the characters to be printed on the console screen.

.PP

The

.B osversion

file contains a textual representation of the operating system's version and parameters.

At the moment, it contains one field: the 9P protocol version, currently

.BR 2000 .

.PP

The

.B config

file contains a copy of the kernel configuration file used to build the kernel.

.PP

The

.B kmesg

file holds the last 16 kilobytes of output written to the console

by the kernel's print statements or by processes writing to

.BR /dev/cons .

It is useful for retrieving boot messages once the boot

process is over.

.PP

The

.B kprint

file may be read to receive a copy of the data written

to the console by the kernel's print statements or by processes

writing to

.BR /dev/cons .

Only data written after the file is opened is available.

If the machine's console is a serial line, the data is sent both to the

console and to

.BR kprint ;

if its console is a graphics screen, the data is sent either to the

display or to

.BR kprint ,

but not both.

(It is advisable not to open

.B kprint

on terminals until you have started

.IR rio (1).)

.PP

The

.B null

file throws away anything written to it

and always returns zero when read.

.PP

The

.B zero

file is a read-only file that produces an infinite stream of zero-valued bytes when read.

.PP

The

.B drivers

file contains, one per line, a listing of the drivers configured in the kernel, in the format

.IP

.EX

#c cons

.EE

.PP

The

.B hostdomain

file contains the name of the authentication domain that

this host belongs to; see

.IR authsrv (6).

Only the user named in

.B /dev/hostowner

may write this.

.PP

The

.B hostowner

file contains the name of the user that owns the console device files.

The hostowner also has group permissions for any local devices.

.PP

Reads from

.B random

return a stream of random numbers.  The numbers are

generated by a low priority kernel process that loops

incrementing a variable.  Each clock tick the variable

is sampled and, if it has changed sufficiently, the last

few bits are appended to a buffer.  This process is inefficient

at best producing at most a few hundred bits a second.

Therefore,

.B random

should be treated as a seed to

pseudo-random number generators which can produce a faster

rate stream.

.PP

Writing the string

.B reboot

to

.B reboot

causes the system to shutdown and, if

possible, restart.

Writing the string

.B reboot

.I kernelpath

loads the named kernel image and restarts,

preserving the kernel configuration in

.BR #ec ,

except that the

.B bootfile

variable is set to

.IR kernelpath .

Only the host

owner has the ability to open this file.

The named kernel may be a Plan 9 executable or

a 32-bit or 64-bit ELF executable.

On some architectures

(e.g.,

.BR mips ),

it may also be a Plan 9 boot image.

.PP

.B Bintime

is a binary interface that provides

the same information as

.B time

.RI ( q.v. ),

in binary form,

and also controls clock frequency and clock trim.

All integers read or written from

.B bintime

are in big endian order.

Unlike the other files, reads and writes do not affect

the offset.  Therefore, there is no need for a seek

back to zero between subsequent accesses.

A read of

.B bintime

returns 24 bytes, three 8 byte numbers, representing nanoseconds

since start of epoch, clock ticks, and clock frequency.

.PP

A write to

.B bintime

is a message with one of 3 formats:

.IP "\f5n\fP<8-byte \f2time\fP>" 1.2i

set the nanoseconds since epoch to the given

.IR time .

.IP "\f5d\fP<8-byte \f2delta\fP><4-byte \f2period\fP>" 1.2i

trim the nanoseconds since epoch by

.I delta

over the next

.I period

seconds.

.IP "\f5f\fP<8-byte \f2freq\fP>" 1.2i

Set the frequency for interpreting clock ticks to be

.I freq

ticks per second.

.SS "Statistics and Dynamic Status"

The rest of the files contain (mostly) read-only strings.

Each string has a fixed length: a

.IR read (2)

of more than that gives a result of that fixed length (the result does not

include a terminating zero byte);

a

.I read

of less than that length leaves the file offset so the

rest of the string (but no more) will be read the next time.

To reread the file without closing it,

.I seek

must be used to reset the offset.

When the file contains numeric data

each number is formatted in decimal.

If the binary number fits in 32 bits, it is formatted as an

11 digit decimal number with

leading blanks and one trailing blank; totaling 12 bytes.

Otherwise, it

is formatted as 21 digit decimal numbers with leading blanks and one

trailing blank; totaling 22 bytes.

.PP

The

.B cputime

file holds six 32-bit numbers, containing the time in milliseconds

that the current process has spent in user mode, system calls,

real elapsed time, and then the time spent, by exited children and their descendants,

in user mode, system calls, and real elapsed time.

.PP

The

.B time

file holds one 32-bit number representing the seconds since start of epoch

and three 64-bit numbers, representing nanoseconds since

start of epoch, clock ticks, and clock frequency.

.PP

A write of a decimal number to

.B time

will set the seconds since epoch.

.PP

The

.B sysname

file holds the textual name of the machine, e.g.

.BR kremvax ,

if known.

.PP

The

.B sysstat

file holds 10 numbers:

processor number, context switches, interrupts, system calls, page faults,

TLB faults, TLB purges, load average, idle time and time spent servicing interrupts.

The load average is in units of milli-CPUs and is decayed over time;

idle time and interrupt time are percentage units;

the others are total counts from boot time.

If the machine is a multiprocessor,

.B sysstat

holds one line per processor.

Writing anything to

.B sysstat

resets all of the counts on all processors.

.PP

The

.B swap

device holds a text block giving memory usage statistics:

.IP

.EX

\fIn\fP memory

\fIn\fP pagesize

\fIn\fP kernel

\fIn\fP/\fIm\fP user

\fIn\fP/\fIm\fP swap

\fIn\fP/\fIm\fP kernel malloc

\fIn\fP/\fIm\fP kernel draw

.EE

.PP

These are total memory (bytes), system page size (bytes),

kernel memory (pages), user memory (pages), swap space (pages),

kernel malloced data (bytes), and kernel graphics data (bytes).

The expression

.IR n / m

indicates

.I n

used out of

.I m

available.

These numbers are not blank padded.

.PP

To turn on swapping, write to

.B swap

the textual file descriptor number of a file or device on which to swap.

See

.IR swap (8).

.PP

The other files served by the

.I cons

device are all single numbers:

.TP 10

.B pgrpid

process group number

.TP

.B pid

process number

.TP

.B ppid

parent's process number

.SH SEE ALSO

.IR draw (3),

.IR keyboard (6),

.IR authsrv (6),

.IR utf (6),

.IR swap (8)

.SH SOURCE

.B /sys/src/9/port/devcons.c

.SH BUGS

For debugging, two control-T's followed by a letter

generate console output and manage debugging:

.L ^T^Td

toggles whether the console debugger will be run if the system fails.

.L ^T^TD

starts the console debugger immediately.

.L ^T^Tk

kills the largest process; use with care.

.L ^T^Tp

prints data about processes.

.L ^T^Tq

prints the run queue for processor 0.

.L ^T^Ts

prints the kernel stack.

.L ^T^Tx

prints data about kernel memory allocation.

.PP

The system can be rebooted by typing

.LR ^T^Tr .