NAME

prog − running programs

SYNOPSIS

­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 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 characters, right justified, followed by a K; and the name of the current program module, up to 28 characters, left justified. 

The read-only ­pgrp file contains the process group identifier, in decimal. 

The read-only ­nsgrp file contains the namespace group identifier, 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 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 contains a description of the open file descriptors in the file descriptor group of the process.  The fields are: the file descriptor index, the open mode (r, w, rw), the ­Qid path and version, the file offset in bytes, and a representation of the path name. 

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. 

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. 

­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.

Reading dbgctl gives updates for some state transitions while the process is being debugged.  Each update is terminated 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 format 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, 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 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) representation of the string.

The ­text file is currently unimplemented. 

SOURCE

­/emu/devprog.c
­/os/port/devprog.c

Plan 9  —  June 29, 2000