PROG(3) PROG(3)
NAME
prog - running programs
SYNOPSIS
bind #p /prog
/prog/n/ctl
/prog/n/dbgctl
/prog/n/exception
/prog/n/fd
/prog/n/heap
/prog/n/ns
/prog/n/nsgrp
/prog/n/pgrp
/prog/n/stack
/prog/n/status
/prog/n/text
/prog/n/wait
...
DESCRIPTION
The prog device serves a two-level directory structure. The
first level contains numbered directories corresponding to
pids of live Limbo processes; each such directory contains a
set of files representing the corresponding process. All
files operate on UTF (see utf(6)) strings.
The read-only status file contains seven space-separated
fields. The fields are: the process and process group iden-
tifiers, each 8 characters right justified; the user name,
at least 10 characters left justified; cpu time in minutes,
seconds and tenths of seconds; the process state, 10 charac-
ters left justified; the amount of memory used by the pro-
cess in units of 1024 bytes, at least 5 characters, right
justified, followed by a K; and the name of the current pro-
gram module, up to 28 characters, left justified.
The read-only pgrp file contains the process group identi-
fier, in decimal.
The read-only nsgrp file contains the namespace group iden-
tifier, in decimal.
The read-only ns file contains a set of mount and bind com-
mands which describe the sys-bind(2) and mount operations
used to construct the name space, in the format of
namespace(6). The last line of the file is a cd command
indicating the working directory.
The read-only wait file may be read to recover information
Page 1 Plan 9 (printed 12/21/24)
PROG(3) PROG(3)
about the exiting children of the process. A read of wait
will block until a child of the process, created after wait
was opened, exits. When such a child exits, it produces a
string with three fields: the pid of the exiting process, a
space, module name enclosed in "'s, a colon, and a possibly
empty error message. The error message will contain at most
64 characters.
The read-only fd file describes the open file descriptors in
the file descriptor group of the process. Each line
describes an open file. The fields are: the file descriptor
index, the open mode (r, w, rw); the type and number of the
device; the path, version and type of the file's qid (see
intro(5)); the file's atomic I/O unit, as defined in sys-
iounit(2)); the file I/O offset in bytes; and the name with
which it was opened.
The read-only exception file gives details of the last
exception to occur in the process, if any. The fields are
the program counter value when the exception occurred, the
module it occurred in and the exception itself, each sepa-
rated by a space. If none, the result is the empty string.
Messages written to the ctl file control the execution of
the process.
kill Kill the process.
killgrp Kill all processes in the same group as the pro-
cess. A process writing to its own ctl file does
not kill itself.
exceptions propagate
Applies to process group leaders only (ie any pro-
cess that executes a system call sys->pctl(Sys-
>NEWPGRP, ... ). If any process in the same group
as the leader incurs an exception which it does not
handle, atomically raise the exception in all pro-
cesses in the group. In this case exceptions are
generated for killed processes as well. This mecha-
nism allows all processes in a process group to
perfom error recovery when one of them faults.
exceptions notifyleader
Applies to process group leaders only. If any pro-
cess in the same group as the leader incurs an
exception which it does not handle, atomically
destroy all processes in the group except for the
leader and raise the exception in the leader. This
error recovery mechanism might be appropriate when
a fault occurs amongst a group of processes and the
Page 2 Plan 9 (printed 12/21/24)
PROG(3) PROG(3)
group leader takes sole responsibilty for recovery.
restricted
Mark all processes that the process spawns in
future as restricted. A restricted process is one
which can run out of memory when a configured limit
has been reached and before total memory is
exhausted. An unrestricted process can allocate
memory until memory is truly exhausted. Typically a
window manager or server might be unrestricted as
they are processes fundamental to the running of a
system.
The dbgctl file provides facilities for debugging a process.
Messages written to the file control the execution of the
process.
step n Step the interpreter for at most n instructions,
or until a breakpoint is reached.
toret Step the interpreter until a return from the cur-
rent activation frame or a breakpoint is reached.
cont Step the interpreter until a breakpoint is
reached.
stop Stop the process as soon as possible. Do not
allow the process to execute again until an unstop
message is received.
unstop Cancel the effect of any previous stop.
bpt set path pc
Set a breakpoint at pc for the module given by
path.
bpt del path pc
Clear a breakpoint if one exists.
Reading dbgctl gives updates for some state transitions
while the process is being debugged. Each update is termi-
nated by a newline.
exited The process exited without error.
broken: error
The process died due to error, a string with up to
64 characters.
send The process is blocked sending on a channel.
recv The process is blocked receiving on a channel.
Page 3 Plan 9 (printed 12/21/24)
PROG(3) PROG(3)
alt The process is blocked in an alt statement.
run The process is unblocked and now ready to run.
new pid The process has spawned a new process identified
by pid.
The read-only stack file contains the dynamic call stack
trace. Each activation frame is described by one line with
six fields, separated by a space: the frame pointer, program
counter, module data pointer, and module code pointer, each
8 hexadecimal digits; the execution method for the module (0
means interpreted, 1 compiled); and the path name of the
module. The top activation frame starts at offset 0.
The heap file may be queried to examine the state of the
process. A data query contains an address, a period, a for-
mat character, and a count. An instruction query contains a
pc, a plus, a mode address, a period, the format I, and a
count. The addresses in the query may be decimal, hexadeci-
mal preceded by 0x or 0X, or octal preceded by 0. Count
gives the number of consecutive data items retrieved by
reading heap starting at offset 0; the format varies accord-
ing to the format character. All data items other than
strings are terminated by a newline.
W 32-bit decimal ints.
B 8-bit unsigned decimal bytes.
V 64-bit decimal bytes.
R 64-bit reals.
I Disassembled Dis instructions.
P 32-bit hexadecimal address, or nil.
The following formats examine properties of specific 32-bit
pointers.
L Examine a list, yielding a pair of hexadecimal
addresses separated by a period, giving the
address of the head and tail of a list. It is an
error to use L on nil.
A Examine an array, yielding a decimal length, a
period, and the address of the 0th element of an
array, or nil.
C Examine a string, yielding the decimal length in
characters, a period, and the utf(6)
Page 4 Plan 9 (printed 12/21/24)
PROG(3) PROG(3)
representation of the string.
M Examine a module reference, yielding the address
of its global data or nil.
The text file is currently unimplemented.
SOURCE
/emu/port/devprog.c
/os/port/devprog.c
Page 5 Plan 9 (printed 12/21/24)