BIND9 Internals: lib/isc/include/isc/backtrace.h File Reference

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

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.

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):

'addrs' is a valid array containing at least 'maxaddrs' void * entries.

'nframes' must be non NULL.

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

'addrp' must be non NULL && '*addrp' == NULL.

'symbolp' must be non NULL && '*symbolp' == NULL.

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):

'symbolp' must be non NULL && '*symbolp' == NULL.

'offsetp' must be non NULL.

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().

backtrace.h File Reference

Data Structures

Defines

Functions

Variables

Detailed Description

Define Documentation

Function Documentation

Variable Documentation