.TH DEBUGGER 2.SH NAMEcisctrace, risctrace, ciscframe, riscframe, localaddr, symoff,fpformat, beieee80ftos, beieeesftos, beieeedftos, leieee80ftos,leieeesftos, leieeedftos, ieeesftos, ieeedftos \- machine-independent debugger functions.SH SYNOPSIS.B #include <u.h>.br.B #include <libc.h>.br.B #include <bio.h>.br.B #include <mach.h>.PP.ta \w'\fLmachines 'u.nf.Bint cisctrace(Map *map, ulong pc, ulong sp, ulong link,.B              Tracer trace).PP.nf.Bint risctrace(Map *map, ulong pc, ulong sp, ulong link,.B              Tracer trace).PP.nf.Bulong ciscframe(Map *map, ulong addr, ulong pc, ulong sp,.B                ulong link).PP.nf.Bulong riscframe(Map *map, ulong addr, ulong pc, ulong sp,.B                ulong link).PP.nf.Bint localaddr(Map *map, char *fn, char *var, long *ret,.B              Rgetter rget).PP.Bint symoff(char *buf, int n, long addr, int type).PP.Bint fpformat(Map *map, Reglist *rp, char *buf, int n, int code).PP.Bint beieee80ftos(char *buf, int n, void *fp).PP.Bint beieeesftos(char *buf, int n, void *fp).PP.Bint beieeedftos(char *buf, int n, void *fp).PP.Bint leieee80ftos(char *buf, int n, void *fp).PP.Bint leieeesftos(char *buf, int n, void *fp).PP.Bint leieeedftos(char *buf, int n, void *fp).PP.Bint ieeesftos(char *buf, int n, ulong f).PP.Bint ieeedftos(char *buf, int n, ulong high, ulong low).PP.Bextern Machdata *machdata;.SH DESCRIPTIONThese functions provide machine-independent implementationsof common debugger functions.Many of the functions assume that global variables.I machand.I machdatapoint to the.I Machand.I Machdatadata structures describing the target architecture.The former contains machine parameters and a description ofthe register set; it is usuallyset by invoking.I crackhdr(see.IR mach (2))to interpret the header of an executable.The.I Machdatastructureis primarily a jump table specifyingfunctions appropriate for processing anexecutable image for a given architecture.Each application is responsible for setting.I machdatato the address of the.I Machdatastructure for the target architecture. Many of the functions described here are notcalled directly; instead, they are invokedindirectly through the.I Machdatajump table..PPThese functions must retrieve data and register contentsfrom an executing image.  The.I Map(see.IR mach (2))data structuresupports the consistent retrieval of data, butno uniform access mechanism exists for registers.The application passes the address of a registerretrieval function as an argument to those functionsrequiring register values.This function, called an.IR Rgetter ,is of the form.PP.RS.B "ulong rget(Map *map, char *name);.RE.PPIt returns the contents of a register when giventhe address of a.I Mapassociated with an executing image and the name of the register..PP.I Cisctraceand.I risctraceunwind the stack for up to 40 levels or until the frame for.I mainis found.  They return thecount of the number of levels unwound.  These functionsprocess stacks conforming to the generic compiler model for.SM RISCand.SM CISCarchitectures, respectively..I Mapis the address of a.I Mapdata structure associated with the imageof an executing process..IR Sp ,.I pcand.I linkare starting values for the stack pointer, program counter, andlink register from which the unwinding is to take place.  Normally, they arethe current contents of the appropriateregisters but they can be any values defining a legitimateprocess context, for example, an alternate stack in amulti-threaded process..I Traceis the address of an application-supplied function to be calledon each iteration as the frame unwinds.  The prototype of thisfunction is:.PP.RS.B "void tracer(Map *map, ulong pc, ulong fp, Symbol *s);.RE.PPwhere.I Mapis the.I Mappointer passed to.I cisctraceor.I risctraceand.I pcand.I fpare the program counter and frame pointer..I Sis the address of a .I Symbolstructure, as defined in.IR symbol (2),containing the symbol table information for thefunction owning the frame (i.e., the function thatcaused the frame to be instantiated)..PP.I Ciscframeand.I riscframecalculate the frame pointer associated witha function.  They are suitable forprograms conforming to the.SM CISCand.SM RISCstack models..I Mapis the address of a.I Mapassociated with the memory image of an executingprocess..I Addris the entry point of the desired function..IR Pc ,.I spand.I linkare the program counter, stack pointer and link register ofan execution context.  As with the stack tracefunctions, these can be the current values of theregisters or any legitimate execution context.The value of the frame pointer is returned.  A returnvalue of zero indicates an error..PP.I Localaddrfills the locationpointed to by.I retwith the address of a local variable..I Mapis the address of a.I Mapassociated with an executing memory image..I Fnand.I varare pointers to the names of the function and variable of interest..I Rgetis the address of a register retrieval function.If both.I fnand.I varare non-zero, the frame for function.I fnis calculated and the address of the automatic orargument named.I varin that frame is returned.If.I varis zero, the address of theframe for function.I fnis returned.In all cases, the frame for the function named.I fnmust be instantiated somewhere on the current stack.If there are multiple frames for the function (that is, ifit is recursive), the most recent frame is used.The search starts from the context defined by thecurrent value of the program counter and stack pointer.If a valid address is found,.I localaddrreturns 1.  A negative return indicates an error inresolving the address..PP.I Symoffconverts a virtual address to a symbolic reference.  Thestring containing that reference is of the form `name+offset', where `name' is the name of thenearest symbol with an address less thanor equal to the target address and `offset' is the hexadecimal offsetbeyond that symbol.  If `offset' is zero, only the name ofthe symbol is printed.  If no symbol is found within 4,096bytes of the address, the address is formatted as a hexadecimaladdress..I Bufis the address of a buffer of.I ncharacters to receive the formatted string..I Addris the address to be converted..I Typeis the type code of the search space:.BR CTEXT ,.BR CDATA ,or.BR CANY ..I Symoffreturns the length of the formatted string contained in.IR buf ..PP.I Fpformatconverts the contents of a floating point register to astring..I Mapis the address of a.I Mapassociated with an executing process..I Rpis the address of a.I Reglistdata structure describing the desired register..I Bufis the address of a buffer of.I ncharacters to hold the resulting string..I Codemust be either.B For.BR f,selecting doubleor single precision, respectively.  If.I codeis.BR F ,the contents of the specified register and the following registerare interpreted as a double precision floating pointnumber; thisis only meaningful for architectures that implementdouble precision floats by combining adjacentsingle precision registers.For.I code.BR f ,the specified register is formattedas a single precision float..I Fpformatreturns 1 if the number is successfully converted or \-1in the case of an error..PP.IR Beieee80ftos ,.I beieeesftosand.I beieeedftosconvert big-endian 80-bit extended, 32-bit single precision,and 64-bit double precision floating point values toa string..IR Leieee80ftos ,.IR leieeesftos ,and.I leieeedftosare the little-endian counterparts..I Bufis the address of a buffer of.I ncharacters to receive the formatted string..I Fpis the address of the floating point value to beconverted.  These functions return the length ofthe resulting string..PP.I Ieeesftosconverts the 32-bit single precision floating point value.IR f ,to a string in.IR buf ,a buffer of.I nbytes.  It returns the length of the resulting string..PP.I Ieeedftosconverts a 64-bit double precision floating point valueto a character string..I Bufis the address of a buffer of.I ncharacters to hold the resulting string..I Highand.I lowcontain the most and least significant 32 bits ofthe floating point value, respectively..I Ieeedftosreturns the number of characters in the resulting string..SH SOURCE.B /sys/src/libmach.SH "SEE ALSO".IR mach (2),.IR symbol (2),.IR errstr (2).SH DIAGNOSTICSSet.IR errstr .