prog - interface to running programs — Inferno 1ed

prog - interface to running programs

bind '#p' /prog

/prog/<n>/ctl
/prog/<n>/dbgctl
/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 structure. The first level contains numbered directories corresponding to pids of live Inferno processes. The second level, for each such directory, contains a set of files representing the corresponding process. All files operate on utf strings.

status (read-only)

process identifiers	8 characters right justified
process group identifiers	8 characters right justified
user name	at least 10 characters left justified
process state	10 characters left justified
process memory	amount of memory used by the process in units of 1024 bytes with at least 5 characters, right justified, followed by a K
name of the current program module	up to 28 characters, left justified

The status file contains six fields, each separated by a blank. The fields are:

process identifiers

8 characters right justified

process group identifiers

8 characters right justified

user name

at least 10 characters left justified

process state

10 characters left justified

process memory

amount of memory used by the process in units of 1024 bytes with at least 5 characters, right justified, followed by a K

name of the current program module

up to 28 characters, left justified


pid of exiting process	decimal value, followed by a space
module name	string, enclosed in double-quotes
error message	zero to 64 characters

ctl

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 process. A process writing to its own ctl file does not kill itself.

dbgctl

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 current activation frame or a breakpoint is reached.
cont	Step the interpreter until a breakpoint is reached.
start	Run the process, ignoring any breakpoints.
bpt set pc path	Set a breakpoint at pc (program counter) for the module given by path.
bpt del pc path	Clear a breakpoint if one exists.

Reading dbgctl gives updates for some state transitions, while the process is being debugged. Each update is terminated by a newline, and includes the following messages:


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.

stack (read-only)

The stack file contains the dynamic call stack trace. Each activation frame is described by one line with six fields, each separated by a space:


Frame pointer	8 hexadecimal digits
Program counter	8 hexadecimal digits
Module data pointer	8 hexadecimal digits
Module code pointer	8 hexadecimal digits
Execution method for the module	0 means interpreted, 1 compiled
The path name of the module

The top activation frame starts at offset 0.

heap

The heap file may be queried to examine the state of the process. The file must be opened for both read and write (ORDWR). Moreover, access to this debugging facility may be not be allowed in production systems.

A data query contains an address, a period, a format character, and a count.

An instruction query contains a pc (program counter), a plus, a mode address, a period, the format I, and a count.

The addresses in the query may be decimal, hexadecimal 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 according to the format character.

All data items other than strings are terminated by a newline.


W	32-bit decimal integers.
B	8-bit unsigned decimal bytes.
V	64-bit decimal integers.
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 representation of the string.

text

The text file is currently unimplemented.

process states


alt	Inter-thread communication processing
send	Ready to transmit a value to another thread
recv	Ready to receive a value from another thread
debug	Debugged
ready	Available to execute instructions
release	Remove from queue to complete a kernel call
exiting	Thread instructions completed
broken	Thread has crashed

Museum

prog - interface to running programs — Inferno 1ed

prog - interface to running programs

Description

status (read-only)

pgrp (read-only)

nsgrp (read-only)

ns (read-only)

wait (read-only)

ctl

dbgctl

stack (read-only)

heap

text

process states

See Also