.TH DEBUG 2.SH NAMEdebug \- process debugging.SH SYNOPSIS.EXinclude "debug.m";debug := load Debug Debug->PATH; Pos: adt{    file:       string;    line:       int;    pos:        int;};Src: adt{    start:      Pos;        # range within source files    stop:       Pos;};Sym: adt{    srctopc:    fn(s: self ref Sym, src: ref Src): int;    pctosrc:    fn(s: self ref Sym, pc: int): ref Src;}; Module: adt{    addsym: fn(m: self ref Module, sym: ref Sym);    stdsym: fn(m: self ref Module);    dis:    fn(m: self ref Module): string;    sbl:    fn(m: self ref Module): string;}; Prog: adt{    cont:   fn(p: self ref Prog): string;    delbpt: fn(p: self ref Prog, dis: string, pc: int): string;    event:  fn(p: self ref Prog): string;    grab:   fn(p: self ref Prog): string;    kill:   fn(p: self ref Prog): string;    setbpt: fn(p: self ref Prog, dis: string, pc: int): string;    stack:  fn(p: self ref Prog): (array of ref Exp, string);    start:  fn(p: self ref Prog): string;    status: fn(p: self ref Prog): (int, string, string, string);    step:   fn(p: self ref Prog, how: int): string;    stop:   fn(p: self ref Prog): string;    unstop: fn(p: self ref Prog): string;}; Exp: adt{    name:   string;    m:      ref Module;     expand: fn(e: self ref Exp): array of ref Exp;    val:    fn(e: self ref Exp): (string, int);    src:    fn(e: self ref Exp): ref Src;    findsym:fn(e: self ref Exp): string;    srcstr: fn(e: self ref Exp): string;}; init:       fn(): int;startprog:  fn(dis, dir: string, ctxt: ref Draw->Context,               argv: list of string): (ref Prog, string);prog:       fn(pid: int): (ref Prog, string);sym:        fn(sbl: string): (ref Sym, string);.EE.SH DESCRIPTION.B Debugis the module interface to the debugging facilities provided by.IR prog (3).It allows facilities for inspection of a program's data structures,as it is running, and to start and stop a running programunder program control..B Initmust be called before any other function to initialise.IR debug 'sglobal state..PP.B Startprogstarts up a program under control of the debug module..I Disis the full pathname of the Dis module to load (which mustbe compatible with.IR command (2);.I diris the current directory in which to put the new process;.I ctxtand.I argvare the arguments given to the new process..B Startprogreturns a tuple.RI ( prog ,\  err )where.I progcan be used to interrogate and control the running process,as detailed below, unless there is an error, in which case.I progwill be nil, and.I errcontains a description of the error..B Progis similar to startprog, except that it attaches to analready running process identified by.IR pid ..SS Controlling a processA.B Progadt provides routines for controlling a running process.It implements the following routines.Unless otherwise stated, they return.B nilon success and a diagnostic string on error..TP 10.IB prog .cont()Run the program until a break point is reached..TP.IB prog .delbpt(\fIdis\fP,\ \fIpc\fP).B Delbptdeletes the breakpoint in the Dis module with filename.I disat Dis instruction.IR pc ..TP.IB prog .event().B Eventwaits for a state transition in the running.I progand returns the new state, as returned by a readof the.B dbgctlfile (see.IR prog (3))..TP.IB prog .grab().B Grabstops the.I progand puts it into a state where single steppingis possible..TP.IB prog .kill().B Killkills.IR prog ..TP.IB prog .setbpt(\fIdis\fP,\ \fIpc\fP).B Setbptsets a breakpoint in the Dis module with filename.I disat Dis instruction.IR pc ..TP.IB prog .stack().B Stackreturns a tuple.RI ( exps ,\  err )where.I expsis an array of.B Expadts, each representing one frame of the currentexecution stack of.IR prog .If an error occurs,.I expswill be nil, and.I errwill contain a description of the error..TP.IB prog .start().B Startruns.I proguntil it hits a breakpoint or exits..TP.IB prog .status().B Statusreturns a tuple(\fIpgrp\fP, \fPuser\fP, \fPstate\fP, \fPmodule\fP)where.I pgrpis the process group id of.IR prog ,.I useris the owner of the process,.I stateis the current state of the process, and.I moduleis the module implementation name of the currentlyexecuting module..TP.IB prog .step(\fIhow\fP).B Stepsteps.I progforward in a manner specified by.IR how ,which is one of the following constants:.RS.TP.B StepExpStep one expression evaluation..TP.B StepStmtStep one source statement..TP.B StepOverStep over one called function..TP.B StepOutStep until the current function has returned..RE.TP.IB prog .stop()Stop.IR progfrom running..TP.IB prog .unstop()Release a program from its stopped state;breakpoints will no longer be triggered..SS "Inspecting data"The.B Expadt provides facilities for inspectingthe data structures of a running Dis process.A hierarchical data structure can be expanded intoan array of its component.BR Exp s,as long as the appropriate symbol information hasbeen located correctly using.B stdsymor.BR addsym ,and.BR findsym ..PPA.B Posrepresents a position in a Limbo source code file;it holds the source file name, the line number (origin 1)and the character within the line (origin 0).The.B Srcadt represents a range in a Limbo source code file;.B Src.startand.B Src.stoprepresent the beginning and the end of therange, respectively..PPA.B Symrepresents a.B .sblsymbol file, and is created by calling.BI sym( p )where.I pis the pathname of the symbol file;.B symreturns a tuple.RI ( sym ,\  err ),where if.I symis nil,.I errcontains an error message.A.B Symcan map between a Dis PC and a source file address,and vice versa.For a given.B Sym.IR sym ,.IB sym .srctopc( src )returns the PC associated with.IR src(or -1 on error);.IB sym .pctosrcconverts the other way (and returns.B nilon error)..PPEach element .I ein the top level stack, as returned by.BR Prog.stack ,has an associated.B Module.IB e .mwhich needs to be associated with a.B Symso that.I debugcan glean from it the type information it needs.Given a module.IR m ,.IB m .stdsym()will try and find a symbol file ina standard place, but this will fail if the symbol fileor the Dis file is in a non-standard place..IB M .addsym( s )sets the symbol file for.I mto the.B Sym.IR s ..IB M .dis()and.IB m .sbl()return the paths of the Dis and symbol files associatedwith.I mrespectively..PPEach top level stack elementexpands into three elements, ``args'', ``locals'',and ``module'', representing the arguments to the function,the function's local variables, and the module-globalvariables of the function's module respectively.Before a top level stack element can be expanded,it is necessary to call.B findsymon it to locate the function's data..TP 10.IB exp .nameThe name of the symbol..TP.IB exp .expand()Expand a hierarchical structure into an array of itscomponent elements. A list element expands into twoelements named ``hd'' and ``tl''; a tuple into elementsnamed ``t0'', ``t1'',..., an array into elements named ``0'', ``1'',..., etc..TP.IB exp .val().B Valreturns a tuple.RI ( s ,\  flag )where.I sis a string representation of the value of.IR exp ,and if.I flagis zero,.I expcannot be expanded..TP.IB exp .src().B Srcreturns the file range associated with.IR exp..TP.IB exp .findsym()If.I expis a top level stack frame (i.e. one of the members of the arrayreturned by.BR Prog.stack )then.B findsymwill attempt to locate its type and name. If it succeeds,it returns the null string, otherwise it returnsan error indicating the problem..TP.IB exp .srcstr().B Srcstrreturns a string representing the position in the source fileof.IR exp ..SH FILES.BI /prog/ pid /*.SH SOURCE.B /appl/lib/debug.b.SH SEE ALSO.IR wm-deb (1),.IR prog (3).SH BUGSThere is no way of looking at the types of the data extracted.