542 lines
14 KiB
Plaintext
542 lines
14 KiB
Plaintext
.TH PROC 3
|
|
.SH NAME
|
|
proc \- running processes
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B bind #p /proc
|
|
.sp 0.3v
|
|
.B /proc/trace
|
|
.BI /proc/ n /args
|
|
.BI /proc/ n /ctl
|
|
.BI /proc/ n /fd
|
|
.BI /proc/ n /fpregs
|
|
.BI /proc/ n /kregs
|
|
.BI /proc/ n /mem
|
|
.BI /proc/ n /note
|
|
.BI /proc/ n /noteid
|
|
.BI /proc/ n /notepg
|
|
.BI /proc/ n /ns
|
|
.BI /proc/ n /proc
|
|
.BI /proc/ n /profile
|
|
.BI /proc/ n /regs
|
|
.BI /proc/ n /segment
|
|
.BI /proc/ n /status
|
|
.BI /proc/ n /text
|
|
.BI /proc/ n /wait
|
|
\&...
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The
|
|
.I proc
|
|
device serves a two-level directory structure.
|
|
The first level contains the
|
|
.B trace
|
|
file (see below) and numbered directories
|
|
corresponding to pids of live processes;
|
|
each such directory contains a set of files
|
|
representing the corresponding process.
|
|
.PP
|
|
The
|
|
.B mem
|
|
file contains the current memory image of the process.
|
|
A read or write at offset
|
|
.IR o ,
|
|
which must be a valid virtual address,
|
|
accesses bytes from address
|
|
.IR o
|
|
up to the end of the memory segment containing
|
|
.IR o .
|
|
Kernel virtual memory, including the kernel stack for the process and
|
|
saved user registers (whose addresses are machine-dependent),
|
|
can be accessed through
|
|
.BR mem .
|
|
Writes are permitted only while the process is in the
|
|
.B Stopped
|
|
state and only to user addresses or registers.
|
|
.PP
|
|
The read-only
|
|
.B proc
|
|
file contains the kernel per-process
|
|
structure.
|
|
Its main use is to recover the kernel stack and program counter
|
|
for kernel debugging.
|
|
.PP
|
|
The files
|
|
.BR regs ,
|
|
.BR fpregs ,
|
|
and
|
|
.BR kregs
|
|
hold representations of the user-level registers, floating-point registers,
|
|
and kernel registers in machine-dependent form.
|
|
The
|
|
.B kregs
|
|
file is read-only.
|
|
.PP
|
|
The read-only
|
|
.B fd
|
|
file lists the open file descriptors of the process.
|
|
The first line of the file is its current directory; subsequent lines list, one per line,
|
|
the open files, giving the decimal file descriptor number; whether the file is open for read
|
|
.RB ( r ),
|
|
write,
|
|
.RB ( w ),
|
|
or both
|
|
.RB ( rw );
|
|
the type, device number, and qid of the file; its I/O unit (the amount of data
|
|
that may be transferred on the file as a contiguous piece; see
|
|
.IR iounit (2)),
|
|
its I/O offset; and its name at the time it was opened.
|
|
.PP
|
|
The read-only
|
|
.B ns
|
|
file contains a textual representation of the process's file name space, in the format of
|
|
.IR namespace (6)
|
|
accepted by
|
|
.B newns
|
|
(see
|
|
.IR auth (2)).
|
|
The last line of the file identifies the current working directory of the process, in the form of a
|
|
.B cd
|
|
command
|
|
(see
|
|
.IR rc (1)).
|
|
The information in this file is based on the names files had when the name space was assembled,
|
|
so the names it contains may be inaccessible if the files have been subsequently renamed or rearranged.
|
|
.PP
|
|
The read-only
|
|
.B segment
|
|
file contains a textual display of the memory segments
|
|
attached to the process. Each line has multiple fields:
|
|
the type of segment (\c
|
|
.BR Stack ,
|
|
.BR Text ,
|
|
.BR Data ,
|
|
.BR Bss ,
|
|
etc.); one-letter flags such as
|
|
.B R
|
|
for read-only, if any;
|
|
starting virtual address, in hexadecimal;
|
|
ending virtual address, and reference count.
|
|
.PP
|
|
The read-only
|
|
.B status
|
|
file contains a string with twelve fields, each followed by a space.
|
|
The fields are:
|
|
.IP \-
|
|
the process name and user name, each 27 characters left justified
|
|
.IP \-
|
|
the process state, 11 characters left justified (see
|
|
.IR ps (1))
|
|
.IP \-
|
|
the six 11-character numbers also held in the process's
|
|
.B #c/cputime
|
|
file
|
|
.IP \-
|
|
the amount of memory used by the process in units of 1024 bytes
|
|
.IP \-
|
|
the base and current scheduling priority, each 11 character numbers
|
|
.PP
|
|
The
|
|
.B args
|
|
file contains the arguments of the program when it was created by
|
|
.IR exec (2).
|
|
Writing to the
|
|
.B args
|
|
file will overwrite its contents.
|
|
If the program was not created by
|
|
.BR exec ,
|
|
such as by
|
|
.IR fork (2),
|
|
its
|
|
.B args
|
|
file will be empty.
|
|
The format of the file is a list of quoted strings suitable for
|
|
.BR tokenize ;
|
|
see
|
|
.IR getfields (2).
|
|
.PP
|
|
The
|
|
.B text
|
|
file is a pseudonym for the file
|
|
from which the process was executed;
|
|
its main use is to recover the symbol table of the process.
|
|
.PP
|
|
The
|
|
.B wait
|
|
file may be read to recover
|
|
records from the exiting children of the process in the format of
|
|
.B await
|
|
(see
|
|
.IR wait (2)).
|
|
If the process has no extant children, living or exited,
|
|
a read of
|
|
.B wait
|
|
will block.
|
|
It is an error for a process to attempt to read its own
|
|
.B wait
|
|
file when it has no children.
|
|
When a process's
|
|
.B wait
|
|
file is being read,
|
|
the process will draw an error
|
|
if it attempts an
|
|
.B await
|
|
system call; similarly, if a process is in an
|
|
.B await
|
|
system call, its
|
|
.B wait
|
|
file cannot be read by any process.
|
|
.PP
|
|
The read-only
|
|
.B profile
|
|
file contains the instruction frequency count information used for multiprocess profiling; see
|
|
.B tprof
|
|
in
|
|
.IR prof (1).
|
|
The information is gleaned by sampling the program's user-level program counter
|
|
at interrupt time.
|
|
.PP
|
|
Strings written to the
|
|
.B note
|
|
file will be posted as a note to the process
|
|
(see
|
|
.IR notify (2)).
|
|
The note should be less than
|
|
.B ERRLEN-1
|
|
characters long;
|
|
the last character is reserved for a terminating NUL character.
|
|
A read of at least
|
|
.B ERRLEN
|
|
characters will retrieve the oldest note posted to the
|
|
process and prevent its delivery to the process.
|
|
The
|
|
.B notepg
|
|
file is similar, but the note will be delivered to all the
|
|
processes in the target process's
|
|
.I note group
|
|
(see
|
|
.IR fork (2)).
|
|
However, if the process doing the write is in the group,
|
|
it will not receive the note.
|
|
The
|
|
.B notepg
|
|
file is write-only.
|
|
.PP
|
|
The textual
|
|
.B noteid
|
|
file may be read to recover an integer identifying the note group of the process
|
|
(see
|
|
.B RFNOTEG
|
|
in
|
|
.IR fork (2)).
|
|
The file may be written to cause the process to change to another note group,
|
|
provided the group exists and is owned by the same user.
|
|
.PP
|
|
The file
|
|
.B /proc/trace
|
|
can be opened once and read to see trace events from processes that have
|
|
had the string
|
|
.B trace
|
|
written to their
|
|
.B ctl
|
|
file.
|
|
Each event produces, in native machine format, the
|
|
.IR pid ,
|
|
a
|
|
.IR type ,
|
|
and a
|
|
.I "time stamp"
|
|
(see
|
|
.B /sys/include/trace.h
|
|
and
|
|
.BR /sys/src/cmd/trace.c ).
|
|
.
|
|
.PP
|
|
The \fLwatchpt\fR file contains a list of the watchpoints set for the process.
|
|
If supported by the hardware, watchpoints can be used to trap accesses to specific addresses.
|
|
Each line in the file has the form "\fItype\fR \fIaddress\fR \fIlength\fR",
|
|
where \fItype\fR consists of the characters \fLr\fR (read), \fLw\fR (write), \fLx\fR (execute) or \fL-\fR (padding character).
|
|
The watchpoint triggers on an access to the \fIlength\fR bytes starting at \fIaddress\fR if the type of the access must match one of the characters in the \fItype\fR field.
|
|
.PP
|
|
Writing to the file either replaces (offset zero) or adds to (offset non-zero) the list of watchpoints.
|
|
Each line written must be terminated by a newline.
|
|
If and only if all lines written comply with the (usually rather idiosyncratic) hardware restrictions, the list is updated; otherwise all changes are discarded.
|
|
Watchpoints can also be cleared by opening the file with \fLOTRUNC\fR (see
|
|
.IR open (2)).
|
|
.PP
|
|
A triggered watchpoint will deliver a \fLsys: watchpoint\fR note which includes a comma-separated list of the watchpoints that were triggered, where 0 corresponds to the first line in the
|
|
.B watchpt
|
|
file, 1 to the second and so forth.
|
|
.SS Control messages
|
|
Textual messages written to the
|
|
.B ctl
|
|
file control the execution of the process.
|
|
Some require that the process is in a particular state
|
|
and return an error if it is not.
|
|
.TP 10n
|
|
.B stop
|
|
Suspend execution of the process, putting it in the
|
|
.B Stopped
|
|
state.
|
|
.TP 10n
|
|
.B start
|
|
Resume execution of a
|
|
.B Stopped
|
|
process.
|
|
.TP 10n
|
|
.B waitstop
|
|
Do not affect the process directly but, like all other messages ending with
|
|
.BR stop ,
|
|
block the process writing the
|
|
.B ctl
|
|
file until the target process is in the
|
|
.B Stopped
|
|
state or exits.
|
|
Also like other
|
|
.B stop
|
|
control messages,
|
|
if the target process would receive a note while the message is pending,
|
|
it is instead stopped and the debugging process is resumed.
|
|
.TP 10n
|
|
.B startstop
|
|
Allow a
|
|
.B Stopped
|
|
process to resume, and then do a
|
|
.B waitstop
|
|
action.
|
|
.TP 10n
|
|
.B hang
|
|
Set a bit in the process so that,
|
|
when it completes an
|
|
.IR exec (2)
|
|
system call, it will enter the
|
|
.B Stopped
|
|
state before returning to user mode.
|
|
This bit is inherited across
|
|
.IR fork (2)
|
|
and
|
|
.IR exec (2).
|
|
.TP 10n
|
|
.B nohang
|
|
Clear the hang bit.
|
|
.TP 10n
|
|
.B private
|
|
Make it impossible to read the process's user memory.
|
|
This property is inherited on
|
|
.IR fork (2),
|
|
cleared on
|
|
.IR exec (2),
|
|
and is not otherwise resettable.
|
|
.TP 10n
|
|
.B noswap
|
|
Don't allow this process to be swapped out. This should
|
|
be used carefully and sparingly or the system could run
|
|
out of memory. It is meant for processes that can't be
|
|
swapped, like the local fileserver implementing the swap
|
|
device and for processes containing sensitive data.
|
|
This property is inherited on
|
|
.IR fork (2),
|
|
cleared on
|
|
.IR exec (2),
|
|
and is not otherwise resettable.
|
|
.TP 10n
|
|
.B kill
|
|
Kill the process the next time it crosses the user/kernel boundary.
|
|
.TP 10n
|
|
.B "close\ \fIn
|
|
Close file descriptor
|
|
.I n
|
|
in the process.
|
|
.TP 10n
|
|
.B closefiles
|
|
Close all open file descriptors in the process.
|
|
.TP 10n
|
|
.B "pri\ \fIn
|
|
Set the base priority for the process to the integer
|
|
.IR n .
|
|
.TP 10n
|
|
.B "wired\ \fIn
|
|
Wire the process to processor
|
|
.IR n .
|
|
.TP 10n
|
|
.B trace
|
|
Without an argument, toggle trace event generation for this process into
|
|
.B /proc/trace
|
|
(see below).
|
|
With a zero argument, tracing for the proc is turned off, with a non-zero numeric
|
|
argument, it is turned on.
|
|
.TP 10n
|
|
.B interrupt
|
|
Interrupt a blocking system call. If no blocking call was in progress,
|
|
the interrupt will be pending and the next attempt to block will be interrupted.
|
|
This is similar to posting a note but, unlike notes, a pending interrupt is not
|
|
cleared when crossing the user/kernel boundary.
|
|
.TP 10n
|
|
.B nointerrupt
|
|
Clear a pending interrupt.
|
|
.TP 10n
|
|
.B "period\ \fInu
|
|
Set the real-time scheduling period of the process to
|
|
.IR nu ,
|
|
where
|
|
.I n
|
|
is an optionally signed number containing an optional decimal point and
|
|
.I u
|
|
is one of
|
|
.BR s ,
|
|
.BR ms ,
|
|
.BR us ,
|
|
.BR µs ,
|
|
.BR ns ,
|
|
or
|
|
empty. The time is interpreted, respectively, as
|
|
.IR seconds ,
|
|
.IR milliseconds ,
|
|
.IR microseconds ,
|
|
.IR microseconds ,
|
|
.IR nanoseconds ,
|
|
or, in the case of an absent units specifier, as
|
|
.IR nanoseconds .
|
|
If the time specifier is signed, it is interpreted as an increment or decrement
|
|
from a previously set value. See also the
|
|
.B admit
|
|
command below.
|
|
.TP 10n
|
|
.B "deadline\ \fInu
|
|
Set the real-time deadline interval of the process to
|
|
.IR nu ,
|
|
where
|
|
.I n
|
|
and
|
|
.I u
|
|
are interpreted as for
|
|
.B period
|
|
above.
|
|
.TP 10n
|
|
.B "cost\ \fInu
|
|
Set the real-time cost (maximum CPU time per period) of the process to
|
|
.IR nu ,
|
|
where
|
|
.I n
|
|
and
|
|
.I u
|
|
are interpreted as for
|
|
.B period
|
|
above.
|
|
.TP 10n
|
|
.B "sporadic
|
|
Use sporadic scheduling for the real-time process. The description of the
|
|
.B admit
|
|
command below contains further details.
|
|
.TP 10n
|
|
.B "yieldonblock
|
|
Make the real-time process yield on blocking I/O.
|
|
The description of the
|
|
.B admit
|
|
command below contains further details.
|
|
.TP 10n
|
|
.B "admit
|
|
Given real-time
|
|
.IR period ,
|
|
.I deadline
|
|
and
|
|
.I cost
|
|
are set (an unset
|
|
.I deadline
|
|
will set
|
|
.I deadline
|
|
to
|
|
.IR period ),
|
|
perform a schedulability test and start scheduling the process as a real-time
|
|
process if the test succeeds. If the test fails, the
|
|
.B write
|
|
will fail with error set to the reason for failure.
|
|
.TP 10n
|
|
.B event
|
|
Add a user event to the
|
|
.B /proc/trace
|
|
file.
|
|
.PD
|
|
.
|
|
.SS Real-time scheduling
|
|
.I Real-time
|
|
processes are periodically
|
|
.IR released ,
|
|
giving them a higher priority than non-real-time processes until they either
|
|
give up the processor voluntarily, they exhaust their CPU allocation, or they reach their
|
|
.IR deadline .
|
|
The moment of release is dictated by the
|
|
.I period
|
|
and whether the process is
|
|
.I sporadic
|
|
or not.
|
|
Non-sporadic processes are called
|
|
.I periodic
|
|
and they are released precisely at intervals of their period (but periods can be skipped
|
|
if the process blocks on I/O).
|
|
Sporadic processes are released whenever they become
|
|
runnable (after being blocked by
|
|
.IR sleep ()
|
|
or I/O), but always at least an interval of
|
|
.I period
|
|
after the previous release.
|
|
.PP
|
|
The
|
|
.I deadline
|
|
of a real-time process specifies that the process must complete within the first
|
|
.I deadline
|
|
seconds of its
|
|
.IR period .
|
|
The dealine must be less than or equal to the period.
|
|
If it is not specified, it is set to the period.
|
|
.PP
|
|
The
|
|
.I cost
|
|
of a real-time process describes the maximum CPU time the process may use per period.
|
|
.PP
|
|
A real-time process can give up the CPU before its deadline is reached
|
|
or its allocation is exhausted.
|
|
It does this by calling
|
|
.IR sleep (0).
|
|
If
|
|
.I yieldonblock
|
|
is specified, it also does it by executing any blocking system call.
|
|
.I Yieldonblock
|
|
is assumed for
|
|
.I sporadic
|
|
processes.
|
|
.PP
|
|
Of the released processes,
|
|
the one with the earliest deadline has the highest priority.
|
|
Care should be taken using spin locks (see
|
|
.IR lock (2))
|
|
because a real-time process spinning on a lock will not give up the processor until
|
|
its CPU allocation is exhausted; this is unlikely to be the desired behavior.
|
|
.PP
|
|
When a real-time process reaches its deadline or exhausts its CPU allocation, it remains
|
|
schedulable, but at a very low priority.
|
|
.PP
|
|
The priority is interpreted by Plan 9's multilevel process scheduler.
|
|
Priorities run from 0 to 19, with higher
|
|
numbers representing higher priorities.
|
|
A process has a base priority and
|
|
a running priority which is less than or equal to the base priority.
|
|
As a process uses up more of its allocated time, its priority is lowered.
|
|
Unless
|
|
explicitly set, user processes have base priority 10, kernel processes
|
|
13.
|
|
Children inherit the parent's base priority.
|
|
.SH FILES
|
|
.nf
|
|
.B /sys/src/9/*/mem.h
|
|
.B /sys/src/9/*/dat.h
|
|
.B /sys/include/trace.h
|
|
.fi
|
|
.SH SEE ALSO
|
|
.IR trace (1),
|
|
.IR debugger (2),
|
|
.IR mach (2),
|
|
.IR cons (3)
|
|
.SH SOURCE
|
|
.B /sys/src/9/port/devproc.c
|