backtrace.h File Reference

provide a back trace of the running process to help debug problems. More...

#include <isc/types.h>

Go to the source code of this file.

Data Structures

struct  isc_backtrace_symmap

Defines

#define ISC_BACKTRACE_H   1

Functions

ISC_LANG_BEGINDECLS isc_result_t isc_backtrace_gettrace (void **addrs, int maxaddrs, int *nframes)
 Get a back trace of the running process above this function itself. On success, addrs[i] will store the address of the call point of the i-th stack frame (addrs[0] is the caller of this function). *nframes will store the total number of frames.
isc_result_t isc_backtrace_getsymbolfromindex (int index, const void **addrp, const char **symbolp)
 Returns the content of the internal symbol table of the given index. On success, *addrsp and *symbolp point to the address and the symbol of the 'index'th entry of the table, respectively. If 'index' is not in the range of the symbol table, ISC_R_RANGE will be returned.
isc_result_t isc_backtrace_getsymbol (const void *addr, const char **symbolp, unsigned long *offsetp)
 Searches the internal symbol table for the symbol that most matches the given 'addr'. On success, '*symbolp' will point to the name of function to which the address 'addr' belong, and '*offsetp' will store the offset from the function's entry address to 'addr'.

Variables

const int isc__backtrace_nsymbols
const isc_backtrace_symmap_t isc__backtrace_symtable []


Detailed Description

provide a back trace of the running process to help debug problems.

This module tries to get a back trace of the process using some platform dependent way when available. It also manages an internal symbol table that maps function addresses used in the process to their textual symbols. This module is expected to be used to help debug when some fatal error happens.

IMPORTANT NOTE: since the (major) intended use case of this module is dumping a back trace on a fatal error, normally followed by self termination, functions defined in this module generally doesn't employ assertion checks (if it did, a program bug could cause infinite recursive calls to a backtrace function). These functions still perform minimal checks and return ISC_R_FAILURE if they detect an error, but the caller should therefore be very careful about the use of these functions, and generally discouraged to use them except in an exit path. The exception is isc_backtrace_getsymbolfromindex(), which is expected to be used in a non-error-handling context and validates arguments with assertion checks.

Definition in file backtrace.h.


Define Documentation

#define ISC_BACKTRACE_H   1

Definition at line 41 of file backtrace.h.


Function Documentation

ISC_LANG_BEGINDECLS isc_result_t isc_backtrace_gettrace ( void **  addrs,
int  maxaddrs,
int *  nframes 
)

Get a back trace of the running process above this function itself. On success, addrs[i] will store the address of the call point of the i-th stack frame (addrs[0] is the caller of this function). *nframes will store the total number of frames.

Requires (note that these are not ensured by assertion checks, see above):

Returns:

Definition at line 211 of file backtrace.c.

References ISC_R_FAILURE, ISC_R_NOTIMPLEMENTED, and UNUSED.

Referenced by assertion_failed(), and default_callback().

isc_result_t isc_backtrace_getsymbolfromindex ( int  index,
const void **  addrp,
const char **  symbolp 
)

Returns the content of the internal symbol table of the given index. On success, *addrsp and *symbolp point to the address and the symbol of the 'index'th entry of the table, respectively. If 'index' is not in the range of the symbol table, ISC_R_RANGE will be returned.

Requires

Returns:

Definition at line 223 of file backtrace.c.

References isc_backtrace_symmap::addr, isc__backtrace_nsymbols, isc__backtrace_symtable, ISC_R_RANGE, ISC_R_SUCCESS, REQUIRE, and isc_backtrace_symmap::symbol.

Referenced by dump_symboltable().

isc_result_t isc_backtrace_getsymbol ( const void *  addr,
const char **  symbolp,
unsigned long *  offsetp 
)

Searches the internal symbol table for the symbol that most matches the given 'addr'. On success, '*symbolp' will point to the name of function to which the address 'addr' belong, and '*offsetp' will store the offset from the function's entry address to 'addr'.

Requires (note that these are not ensured by assertion checks, see above):

Returns:

Definition at line 264 of file backtrace.c.

References isc_backtrace_symmap::addr, isc__backtrace_nsymbols, isc__backtrace_symtable, ISC_R_FAILURE, ISC_R_NOTFOUND, ISC_R_SUCCESS, isc_backtrace_symmap::symbol, and symtbl_compare().

Referenced by assertion_failed(), and default_callback().


Variable Documentation

const int isc__backtrace_nsymbols

Definition at line 33 of file backtrace-emptytbl.c.

Referenced by dump_symboltable(), isc_backtrace_getsymbol(), isc_backtrace_getsymbolfromindex(), and symtbl_compare().

const isc_backtrace_symmap_t isc__backtrace_symtable[]

Definition at line 34 of file backtrace-emptytbl.c.

Referenced by isc_backtrace_getsymbol(), isc_backtrace_getsymbolfromindex(), and symtbl_compare().


Generated on Tue Apr 28 17:41:14 2015 by Doxygen 1.5.4 for BIND9 Internals 9.11.0pre-alpha