PROG(3) PROG(3)
NAME
prog - running programs
SYNOPSIS
bind #p /prog
/prog/n/ctl
/prog/n/dbgctl
/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 six fields, separated by
a space. The fields are: the process and process group
identifiers, each 8 characters right justified; the user
name, at least 10 characters left justified; the process
state, 10 characters left justified; the amount of memory
used by the process in units of 1024 bytes, at least 5 char-
acters, right justified, followed by a K; and the name of
the current program module, up to 28 characters, left justi-
fied.
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 an ordered set of triples,
separated by a space, which describe the sys-bind(2) and
mount operations used to construct the name space. The
fields are: the integer flags, the to file, and the from
file; see sys-bind(2).
The read-only wait file may be read to recover information
about the exiting children of the process. A read of wait
Page 1 Plan 9 (printed 4/19/24)
PROG(3) PROG(3)
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, 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 and version of the file's qid (see
intro(5)); the file offset in bytes; and the name with which
it was opened.
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.
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.
detach Run the process without any debugging.
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.
Page 2 Plan 9 (printed 4/19/24)
PROG(3) PROG(3)
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.
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.
Page 3 Plan 9 (printed 4/19/24)
PROG(3) PROG(3)
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) representa-
tion of the string.
The text file is currently unimplemented.
SOURCE
/emu/devprog.c
/os/port/devprog.c
Page 4 Plan 9 (printed 4/19/24)