MACH-STACK(3) MACH-STACK(3)
NAME
stacktrace, localaddr, unwindframe, windindex, windreglocs -
stack traces
SYNOPSIS
#include <u.h>
#include <libc.h>
#include <mach.h>
int stacktrace(Map *map, Rgetter rget, Tracer trace)
int localaddr(Map *map, Regs *regs, char *fn, char *val,
ulong *val)
int unwindframe(Map *map, Regs *regs, ulong *next, Symbol
*sym)
int windindex(char *regname)
Loc* windreglocs(void)
DESCRIPTION
Stacktrace provides machine-independent implementations of
process stack traces. They must retrieve data and register
contents from an executing image. Sometimes the desired
registers are not the current registers but rather a set of
saved registers stored elsewhere in memory. The caller may
specify an initial register set in the form of an Rgetter
function, of the form
ulong rget(Map *map, char *name)
It returns the contents of a register when given a map and a
register name. It is usually sufficient for the register
function to return meaningful values only for SP and PC, and
for the link register (usually LR) on CISC machines.
Given the map and the rgetter, stacktrace unwinds the stack
starting at the innermost function. At each level in the
trace, it calls the tracer function, which has the form
int trace(Map *map, ulong pc, ulong callerpc,
Rgetter rget, Symbol *s)
The tracer is passed the map, the current program counter,
the program counter of the caller (zero if the caller is
unknown), a new rget function, and a symbol (see mach-
symbol(3)) describing the current function (nil if no symbol
is known). The value returned by the tracer controls
whether the stack trace continues: a zero or negative return
MACH-STACK(3) MACH-STACK(3)
value stops the trace, while a positive return value contin-
ues it.
The rgetter passed to the tracer is not the rgetter passed
to stacktrace itself. Instead, it is a function returning
the register values at the time of the call, to the extent
that they can be reconstructed. The most common use for
this rgetter is as an argument to lget4, etc., when evaluat-
ing the locations of local variables.
Localaddr uses stacktrace to walk up the stack looking for
the innermost instance of a function named fn ; once it
finds the function, it looks for the parameter or local
variable var, storing the address of the variable in val.
Unwindframe is the low-level function on which stacktrace is
built. Given the current memory image in map and the cur-
rent register set in regs , unwindframe fills in next with
the values of the register set at the time of the call to
the function in the current program counter. Sym should be
the symbol corresponding to the current function, if avail-
able.
The next array holds only the winding registers, typically
the caller-save registers and the program counter and stack
pointer. The order of registers in the array is called the
winding order. The winding set can be found in the array
mach->windreg, which has mach->nwindreg entries. Windindex
returns the index of the named register in the winding
order. Windreglocs returns an array of Loc structures cor-
responding to the winding registers, in the winding order.
EXAMPLE
The following code writes a simple stack trace to standard
output, stopping after at most 20 stack frames.
static int
trace(Map *map, ulong pc, ulong callerpc,
Rgetter rget, Symbol *s, int depth)
{
char buf[512];
int i, first;
u32int v;
Symbol s2;
if(sym)
print("%s+%lx", s->name, pc - loceval(s->loc));
else
print("%lux", pc);
print("(");
first = 0;
for(i=0; indexlsym(s, &i, &s2)>=0; i++){
if(s.class != CPARAM)
MACH-STACK(3) MACH-STACK(3)
continue;
if(first++)
print(", ");
if(lget4(map, rget, s->loc, &v) >= 0)
print("%s=%#lux", s->name, (ulong)v);
else
print("%s=???", s->name);
}
print(") called from ");
symoff(buf, sizeof buf, callerpc, CTEXT);
print("%s\n", buf);
return depth < 20;
}
if(stacktrace(map, nil, trace) <= 0)
print("no stack frame0);
SOURCE
/src/libmach
SEE ALSO
mach(3)
BUGS
Need to talk about Regs