term% cat index.txt PROC(3) Library Functions Manual PROC(3)
NAME
proc - running processes
SYNOPSIS
bind #p /proc
/proc/trace
/proc/n/args
/proc/n/ctl
/proc/n/fd
/proc/n/fpregs
/proc/n/kregs
/proc/n/mem
/proc/n/note
/proc/n/noteid
/proc/n/notepg
/proc/n/ns
/proc/n/proc
/proc/n/profile
/proc/n/regs
/proc/n/segment
/proc/n/status
/proc/n/text
/proc/n/wait
...
DESCRIPTION
The proc device serves a two-level directory structure. The first
level contains the trace file (see below) and numbered directories cor‐
responding to pids of live processes; each such directory contains a
set of files representing the corresponding process.
The mem file contains the current memory image of the process. A read
or write at offset o, which must be a valid virtual address, accesses
bytes from address o up to the end of the memory segment containing o.
Kernel virtual memory, including the kernel stack for the process and
saved user registers (whose addresses are machine-dependent), can be
accessed through mem. Writes are permitted only while the process is
in the Stopped state and only to user addresses or registers.
The read-only proc file contains the kernel per-process structure. Its
main use is to recover the kernel stack and program counter for kernel
debugging.
The files regs, fpregs, and kregs hold representations of the user-
level registers, floating-point registers, and kernel registers in ma‐
chine-dependent form. The kregs file is read-only.
The read-only 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 (r), write, (w), or both
(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 iounit(2)), its I/O offset; and its name at the time it was
opened.
The read-only ns file contains a textual representation of the
process's file name space, in the format of namespace(6) accepted by
newns (see auth(2)). The last line of the file identifies the current
working directory of the process, in the form of a cd command (see
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 in‐
accessible if the files have been subsequently renamed or rearranged.
The read-only segment file contains a textual display of the memory
segments attached to the process. Each line has multiple fields: the
type of segment (Stack, Text, Data, Bss, etc.); one-letter flags such
as R for read-only, if any; starting virtual address, in hexadecimal;
ending virtual address, and reference count.
The read-only status file contains a string with twelve fields, each
followed by a space. The fields are:
- the process name and user name, each 27 characters left justi‐
fied
- the process state, 11 characters left justified (see ps(1))
- the six 11-character numbers also held in the process's
#c/cputime file
- the amount of memory used by the process in units of 1024 bytes
- the base and current scheduling priority, each 11 character num‐
bers
The args file contains the arguments of the program when it was created
by exec(2). Writing to the args file will overwrite its contents. If
the program was not created by exec, such as by fork(2), its args file
will be empty. The format of the file is a list of quoted strings
suitable for tokenize; see getfields(2).
The 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.
The wait file may be read to recover records from the exiting children
of the process in the format of await (see wait(2)). If the process
has no extant children, living or exited, a read of wait will block.
It is an error for a process to attempt to read its own wait file when
it has no children. When a process's wait file is being read, the
process will draw an error if it attempts an await system call; simi‐
larly, if a process is in an await system call, its wait file cannot be
read by any process.
The read-only profile file contains the instruction frequency count in‐
formation used for multiprocess profiling; see tprof in prof(1). The
information is gleaned by sampling the program's user-level program
counter at interrupt time.
Strings written to the note file will be posted as a note to the
process (see notify(2)). The note should be less than ERRLEN-1 charac‐
ters long; the last character is reserved for a terminating NUL charac‐
ter. A read of at least ERRLEN characters will retrieve the oldest
note posted to the process and prevent its delivery to the process.
The notepg file is similar, but the note will be delivered to all the
processes in the target process's note group (see fork(2)). However,
if the process doing the write is in the group, it will not receive the
note. The notepg file is write-only.
The textual noteid file may be read to recover an integer identifying
the note group of the process (see RFNOTEG in fork(2)). The file may
be written to cause the process to change to another note group, pro‐
vided the group exists and is owned by the same user.
The file /proc/trace can be opened once and read to see trace events
from processes that have had the string trace written to their ctl
file. Each event produces, in native machine format, the pid, a type,
and a time stamp (see /sys/include/trace.h and /sys/src/cmd/trace.c).
Control messages
Textual messages written to the 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.
stop Suspend execution of the process, putting it in the Stopped
state.
start Resume execution of a Stopped process.
waitstop Do not affect the process directly but, like all other mes‐
sages ending with stop, block the process writing the ctl
file until the target process is in the Stopped state or ex‐
its. Also like other 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.
startstop Allow a Stopped process to resume, and then do a waitstop ac‐
tion.
hang Set a bit in the process so that, when it completes an
exec(2) system call, it will enter the Stopped state before
returning to user mode. This bit is inherited across fork(2)
and exec(2).
nohang Clear the hang bit.
private Make it impossible to read the process's user memory. This
property is inherited on fork(2), cleared on exec(2), and is
not otherwise resettable.
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 fork(2), cleared on exec(2), and is not other‐
wise resettable.
kill Kill the process the next time it crosses the user/kernel
boundary.
close n Close file descriptor n in the process.
closefiles
Close all open file descriptors in the process.
pri n Set the base priority for the process to the integer n.
wired n Wire the process to processor n.
trace Without an argument, toggle trace event generation for this
process into /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.
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.
nointerrupt
Clear a pending interrupt.
period nu Set the real-time scheduling period of the process to nu,
where n is an optionally signed number containing an optional
decimal point and u is one of s, ms, us, µs, ns, or empty.
The time is interpreted, respectively, as seconds, millisec‐
onds, microseconds, microseconds, nanoseconds, or, in the
case of an absent units specifier, as nanoseconds. If the
time specifier is signed, it is interpreted as an increment
or decrement from a previously set value. See also the admit
command below.
deadline nu
Set the real-time deadline interval of the process to nu,
where n and u are interpreted as for period above.
cost nu Set the real-time cost (maximum CPU time per period) of the
process to nu, where n and u are interpreted as for period
above.
sporadic Use sporadic scheduling for the real-time process. The de‐
scription of the admit command below contains further de‐
tails.
yieldonblock
Make the real-time process yield on blocking I/O.
The description of the admit command below contains further
details.
admit Given real-time period, deadline and cost are set (an unset
deadline will set deadline to period), perform a schedulabil‐
ity test and start scheduling the process as a real-time
process if the test succeeds. If the test fails, the write
will fail with error set to the reason for failure.
event Add a user event to the /proc/trace file.
Real-time scheduling
Real-time processes are periodically 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 deadline. The moment of release is dictated by the period and
whether the process is sporadic or not. Non-sporadic processes are
called periodic and they are released precisely at intervals of their
period (but periods can be skipped if the process blocks on I/O). Spo‐
radic processes are released whenever they become runnable (after being
blocked by sleep() or I/O), but always at least an interval of period
after the previous release.
The deadline of a real-time process specifies that the process must
complete within the first deadline seconds of its period. The dealine
must be less than or equal to the period. If it is not specified, it
is set to the period.
The cost of a real-time process describes the maximum CPU time the
process may use per period.
A real-time process can give up the CPU before its deadline is reached
or its allocation is exhausted. It does this by calling sleep(0). If
yieldonblock is specified, it also does it by executing any blocking
system call. Yieldonblock is assumed for sporadic processes.
Of the released processes, the one with the earliest deadline has the
highest priority. Care should be taken using spin locks (see 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.
When a real-time process reaches its deadline or exhausts its CPU allo‐
cation, it remains schedulable, but at a very low priority.
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.
FILES
/sys/src/9/*/mem.h
/sys/src/9/*/dat.h
/sys/include/trace.h
SEE ALSO
trace(1), debugger(2), mach(2), cons(3)
SOURCE
/sys/src/9/port/devproc.c
PROC(3)