PROC(3) 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 corresponding to pids of live processes; each
such directory contains a set of files representing the cor-
responding process.
The mem file contains the current memory image of the pro-
cess. 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 ker-
nel registers in machine-dependent form. The kregs file is
read-only.
Page 1 Plan 9 (printed 12/21/24)
PROC(3) PROC(3)
The read-only fd file lists the open file descriptors of the
process. The first line of the file is its current direc-
tory; 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 inac-
cessible 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 mul-
tiple 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
justified
- 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 char-
acter numbers
The args file contains the arguments of the program when it
was created by exec(2). Writing to the args file will over-
write 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).
Page 2 Plan 9 (printed 12/21/24)
PROC(3) PROC(3)
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 exit-
ing 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; similarly, 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 fre-
quency count information 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 characters long; the last character is reserved for
a terminating NUL character. A read of at least ERRLEN
characters will retrieve the oldest note posted to the pro-
cess 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, provided 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).
The watchpt 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 "type address length", where type
consists of the characters r (read), w (write), x (execute)
or - (padding character). The watchpoint triggers on an
access to the length bytes starting at address if the type
of the access must match one of the characters in the type
field.
Page 3 Plan 9 (printed 12/21/24)
PROC(3) PROC(3)
Writing to the file either replaces (offset zero) or adds to
(offset non-zero) the list of watchpoints. Each line writ-
ten 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 OTRUNC (see open(2)).
A triggered watchpoint will deliver a sys: watchpoint note
which includes a comma-separated list of the watchpoints
that were triggered, where 0 corresponds to the first line
in the watchpt file, 1 to the second and so forth.
Control messages
Textual messages written to the ctl file control the execu-
tion 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 messages ending with stop, block the process
writing the ctl file until the target process is
in the Stopped state or exits. 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 action.
hang Set a bit in the process so that, when it com-
pletes 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 mem-
ory. This property is inherited on fork(2),
cleared on exec(2), and is not otherwise reset-
table.
noswap Don't allow this process to be swapped out. This
should be used carefully and sparingly or the sys-
tem could run out of memory. It is meant for pro-
cesses that can't be swapped, like the local file-
server implementing the swap device and for
Page 4 Plan 9 (printed 12/21/24)
PROC(3) PROC(3)
processes containing sensitive data. This prop-
erty is inherited on fork(2), cleared on exec(2),
and is not otherwise 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 inte-
ger n.
fixedpri n
Fixate the process priority to the integer n. In
contrast to pri, the kernel will not automatically
lower the priority based on the processes cpu
usage.
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 pend-
ing and the next attempt to block will be inter-
rupted. 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 con-
taining an optional decimal point and u is one of
s, ms, us, µs, ns, or empty. The time is inter-
preted, respectively, as seconds, milliseconds,
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
Page 5 Plan 9 (printed 12/21/24)
PROC(3) PROC(3)
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 description of the admit command below con-
tains further details.
yieldonblock
Make the real-time process yield on blocking I/O.
The description of the admit command below con-
tains further details.
admit Given real-time period, deadline and cost are set
(an unset deadline will set deadline to period),
perform a schedulability 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).
Sporadic processes are released whenever they become runn-
able (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 pro-
cess 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.
Page 6 Plan 9 (printed 12/21/24)
PROC(3) PROC(3)
Of the released processes, the one with the earliest dead-
line has the highest priority. Care should be taken using
spin locks (see lock(2)) because a real-time process spin-
ning 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 allocation, 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 prior-
ity and a running priority which is less than or equal to
the base priority. As a process uses up more of its allo-
cated 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
Page 7 Plan 9 (printed 12/21/24)