backtrace.h

Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2009  Internet Systems Consortium, Inc. ("ISC")
00003  *
00004  * Permission to use, copy, modify, and/or distribute this software for any
00005  * purpose with or without fee is hereby granted, provided that the above
00006  * copyright notice and this permission notice appear in all copies.
00007  *
00008  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
00009  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
00010  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
00011  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
00012  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
00013  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
00014  * PERFORMANCE OF THIS SOFTWARE.
00015  */
00016 
00017 /* $Id: backtrace.h,v 1.2 2009/09/01 18:40:25 jinmei Exp $ */
00018 
00019 /*! \file isc/backtrace.h
00020  * \brief provide a back trace of the running process to help debug problems.
00021  *
00022  * This module tries to get a back trace of the process using some platform
00023  * dependent way when available.  It also manages an internal symbol table
00024  * that maps function addresses used in the process to their textual symbols.
00025  * This module is expected to be used to help debug when some fatal error
00026  * happens.
00027  *
00028  * IMPORTANT NOTE: since the (major) intended use case of this module is
00029  * dumping a back trace on a fatal error, normally followed by self termination,
00030  * functions defined in this module generally doesn't employ assertion checks
00031  * (if it did, a program bug could cause infinite recursive calls to a
00032  * backtrace function).  These functions still perform minimal checks and return
00033  * ISC_R_FAILURE if they detect an error, but the caller should therefore be
00034  * very careful about the use of these functions, and generally discouraged to
00035  * use them except in an exit path.  The exception is
00036  * isc_backtrace_getsymbolfromindex(), which is expected to be used in a
00037  * non-error-handling context and validates arguments with assertion checks.
00038  */
00039 
00040 #ifndef ISC_BACKTRACE_H
00041 #define ISC_BACKTRACE_H 1
00042 
00043 /***
00044  ***    Imports
00045  ***/
00046 
00047 #include <isc/types.h>
00048 
00049 /***
00050  *** Types
00051  ***/
00052 struct isc_backtrace_symmap {
00053         void            *addr;
00054         const char      *symbol;
00055 };
00056 
00057 extern const int isc__backtrace_nsymbols;
00058 extern const isc_backtrace_symmap_t isc__backtrace_symtable[];
00059 
00060 /***
00061  *** Functions
00062  ***/
00063 
00064 ISC_LANG_BEGINDECLS
00065 isc_result_t
00066 isc_backtrace_gettrace(void **addrs, int maxaddrs, int *nframes);
00067 /*%<
00068  * Get a back trace of the running process above this function itself.  On
00069  * success, addrs[i] will store the address of the call point of the i-th
00070  * stack frame (addrs[0] is the caller of this function).  *nframes will store
00071  * the total number of frames.
00072  *
00073  * Requires (note that these are not ensured by assertion checks, see above):
00074  *
00075  *\li   'addrs' is a valid array containing at least 'maxaddrs' void * entries.
00076  *
00077  *\li   'nframes' must be non NULL.
00078  *
00079  * Returns:
00080  *
00081  *\li   #ISC_R_SUCCESS
00082  *\li   #ISC_R_FAILURE
00083  *\li   #ISC_R_NOTFOUND
00084  *\li   #ISC_R_NOTIMPLEMENTED
00085  */
00086 
00087 isc_result_t
00088 isc_backtrace_getsymbolfromindex(int index, const void **addrp,
00089                                  const char **symbolp);
00090 /*%<
00091  * Returns the content of the internal symbol table of the given index.
00092  * On success, *addrsp and *symbolp point to the address and the symbol of
00093  * the 'index'th entry of the table, respectively.  If 'index' is not in the
00094  * range of the symbol table, ISC_R_RANGE will be returned.
00095  *
00096  * Requires
00097  *
00098  *\li   'addrp' must be non NULL && '*addrp' == NULL.
00099  *
00100  *\li   'symbolp' must be non NULL && '*symbolp' == NULL.
00101  *
00102  * Returns:
00103  *
00104  *\li   #ISC_R_SUCCESS
00105  *\li   #ISC_R_RANGE
00106  */
00107 
00108 isc_result_t
00109 isc_backtrace_getsymbol(const void *addr, const char **symbolp,
00110                         unsigned long *offsetp);
00111 /*%<
00112  * Searches the internal symbol table for the symbol that most matches the
00113  * given 'addr'.  On success, '*symbolp' will point to the name of function
00114  * to which the address 'addr' belong, and '*offsetp' will store the offset
00115  * from the function's entry address to 'addr'.
00116  *
00117  * Requires (note that these are not ensured by assertion checks, see above):
00118  *
00119  *\li   'symbolp' must be non NULL && '*symbolp' == NULL.
00120  *
00121  *\li   'offsetp' must be non NULL.
00122  *
00123  * Returns:
00124  *
00125  *\li   #ISC_R_SUCCESS
00126  *\li   #ISC_R_FAILURE
00127  *\li   #ISC_R_NOTFOUND
00128  */
00129 ISC_LANG_ENDDECLS
00130 
00131 #endif  /* ISC_BACKTRACE_H */

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