stacktrace Namespace Reference

Detailed Description

Holds the C-style interface for the stack trace routines.

Classes

struct StackFrame

Stores information about a single stack frame. More...

Typedefs

typedef int machineInstruction

typedef in case type needs to change on other platforms (i.e. long for 64 bit architectures?)

Functions

int loadStackTraceSymbols (const char *ST_UNUSED(objfile))

int unrollStackFrame (struct StackFrame *curFrame, struct StackFrame *nextFrame)

stores information about the caller to curFrame into nextFrame

void getCurrentStackFrame (struct StackFrame *frame)

stores information about the caller's stack frame into frame

void freeStackTrace (struct StackFrame *frame)

frees a list of StackFrames, such as is returned by recordStackTrace

StackFrame * allocateStackTrace (unsigned int size)

preallocates a stack trace of a particular size (doesn't actually perform a stack trace, merely allocates the linked list)

StackFrame * recordStackTrace (unsigned int limit=-1U, unsigned int skip=0)

repeatedly calls unrollStackFrame() until the root frame is reached or limit is hit, skipping the top skip frames

StackFrame * recordOverStackTrace (struct StackFrame *frame, unsigned int skip=0)

repeatedly calls unrollStackFrame() until the root frame is reached or end of frame list is hit, skipping the top skip frames

void beginDisplay ()

attempts to read symbol information and displays stack trace header

void displayStackFrame (unsigned int ST_UNUSED(depth), const struct StackFrame *frame)

void completeDisplay (int isend)

releases symbol information used during display

void displayCurrentStackTrace (unsigned int limit=-1U, unsigned int skip=0)

dumps current stack trace to stderr, up to limit depth and skipping the top skip frames

void displayStackTrace (const struct StackFrame *frame)

dumps stored stack trace to stderr

int loadStackTraceSymbols (const char *objfile)

Must be called with the object file containing debugging symbols before symbolic output can be displayed.

Variables

const char * BFD_DEFAULT_TARGET = "powerpc-apple-darwin8.5.0"

target string to use when opening symbol files if host architecture can't be detected

Typedef Documentation

typedef int stacktrace::machineInstruction

typedef in case type needs to change on other platforms (i.e. long for 64 bit architectures?)

Definition at line 12 of file StackTrace.h.

Function Documentation

int stacktrace::loadStackTraceSymbols ( const char * ST_UNUSED(objfile) )

Definition at line 89 of file StackTrace.cc.

int stacktrace::unrollStackFrame	(	struct StackFrame *	curFrame,
		struct StackFrame *	nextFrame
	)

stores information about the caller to curFrame into nextFrame

Returns:: 0 if error occurred (i.e. bottom of the stack), non-zero upon success nextFrame can be the same instance as curFrame, will update in place. curFrame->caller will be set to nextFrame.

Definition at line 95 of file StackTrace.cc.

Referenced by displayCurrentStackTrace(), getCurrentStackFrame(), ProcessID::getID(), recordOverStackTrace(), and recordStackTrace().

void stacktrace::getCurrentStackFrame ( struct StackFrame * frame )

stores information about the caller's stack frame into frame

Definition at line 282 of file StackTrace.cc.

Referenced by displayCurrentStackTrace(), ProcessID::getID(), recordOverStackTrace(), and recordStackTrace().

void stacktrace::freeStackTrace ( struct StackFrame * frame )

frees a list of StackFrames, such as is returned by recordStackTrace

Definition at line 323 of file StackTrace.cc.

struct StackFrame * stacktrace::allocateStackTrace ( unsigned int size )

preallocates a stack trace of a particular size (doesn't actually perform a stack trace, merely allocates the linked list)

this is a good idea if you want to do a stack trace within an exception handler, which might have been triggered by running out of heap

Definition at line 333 of file StackTrace.cc.

struct StackFrame * stacktrace::recordStackTrace	(	unsigned int	limit = `-1U`,
		unsigned int	skip = `0`
	)

repeatedly calls unrollStackFrame() until the root frame is reached or limit is hit, skipping the top skip frames

pass -1U for limit to request unlimited trace, and 0 to start with the function calling recordStackTrace

Definition at line 344 of file StackTrace.cc.

struct StackFrame * stacktrace::recordOverStackTrace	(	struct StackFrame *	frame,
		unsigned int	skip = `0`
	)

repeatedly calls unrollStackFrame() until the root frame is reached or end of frame list is hit, skipping the top skip frames

This is handy for reusing previously allocated frames, returns the unused portion (if return value equals frame, none were used -- implies never cleared skip)

Definition at line 378 of file StackTrace.cc.

void stacktrace::beginDisplay ( )

attempts to read symbol information and displays stack trace header

Definition at line 406 of file StackTrace.cc.

Referenced by displayCurrentStackTrace(), and displayStackTrace().

void stacktrace::displayStackFrame	(	unsigned int	ST_UNUSED(depth),
		const struct StackFrame *	frame
	)

Definition at line 627 of file StackTrace.cc.

Referenced by displayCurrentStackTrace(), and displayStackTrace().

void stacktrace::completeDisplay ( int isend )

releases symbol information used during display

Definition at line 634 of file StackTrace.cc.

Referenced by displayCurrentStackTrace(), and displayStackTrace().

void stacktrace::displayCurrentStackTrace	(	unsigned int	limit = `-1U`,
		unsigned int	skip = `0`
	)

dumps current stack trace to stderr, up to limit depth and skipping the top skip frames

pass -1U for limit to request unlimited trace, and 0 to start with the function calling recordStackTrace

Definition at line 657 of file StackTrace.cc.

Referenced by MotionManager::processMsg().

void stacktrace::displayStackTrace ( const struct StackFrame * frame )

dumps stored stack trace to stderr

Definition at line 683 of file StackTrace.cc.

int stacktrace::loadStackTraceSymbols ( const char * objfile )

Must be called with the object file containing debugging symbols before symbolic output can be displayed.

Parameters:

objfile

the file containing debugging symbols, in a format supported by libBFD; generally this is the executable itself (compiled with -g), so pass argv[0]

Display done before this has been called will display numeric addresses, which may still be decoded externally -- this is handy for embedded systems which may not be able to hold the debugging symbols and BFD library themselves, but the numerical values can be looked up on the desktop workstation.

Returns:: zero on success, negative if file could not be found, positive if it could not be parsed (wrong file type) or any other internal error

Variable Documentation

const char* stacktrace::BFD_DEFAULT_TARGET = "powerpc-apple-darwin8.5.0"

target string to use when opening symbol files if host architecture can't be detected

Definition at line 41 of file StackTrace.cc.