PROC(3) PROC(3)
NAME
proc - running processes
SYNOPSIS
bind #p /proc
/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 numbered directories corresponding 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 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/26/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 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, except its
stack, in units of 1024 bytes
- the base and current scheduling priority, each 11 char-
acter numbers
The read-only args file contains the arguments of the pro-
gram when it was created by exec(2). 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.
Page 2 Plan 9 (printed 12/26/24)
PROC(3) PROC(3)
The wait file may be read to recover Waitmsg records from
the exiting children of the process. 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 a wait system call; similarly, if a process is
in a wait system call, its wait file cannot be read by any
process.
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 a fork(2).
closefiles
Close all open file descriptors in the process.
nohang Clear the hang bit.
kill Kill the process the next time it crosses the
user/kernel boundary.
pri n Set the base priority for the process to the inte-
ger n.
wire n Wire the process to processor n.
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
Page 3 Plan 9 (printed 12/26/24)
PROC(3) PROC(3)
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.
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.
FILES
/sys/src/9/*/mem.h
/sys/src/9/*/dat.h
SEE ALSO
debugger(2), mach(2), cons(3)
SOURCE
/sys/src/9/port/devproc.c
Page 4 Plan 9 (printed 12/26/24)