backtrace.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2013, Digium, Inc.
00005  *
00006  * Matt Jordan <mjordan@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Asterisk backtrace generation
00021  *
00022  * This file provides backtrace generation utilities
00023  */
00024 
00025 
00026 #ifndef BACKTRACE_H_
00027 #define BACKTRACE_H_
00028 
00029 #define AST_MAX_BT_FRAMES 32
00030 
00031 #ifdef HAVE_BKTR
00032 #define ast_bt_get_addresses(bt) __ast_bt_get_addresses((bt))
00033 #define ast_bt_create() __ast_bt_create()
00034 #define ast_bt_destroy(bt) __ast_bt_destroy((bt))
00035 #define ast_bt_get_symbols(addresses, num_frames) __ast_bt_get_symbols((addresses), (num_frames))
00036 #else
00037 #define ast_bt_get_addresses(bt) 0
00038 #define ast_bt_create() NULL
00039 #define ast_bt_destroy(bt) NULL
00040 #define ast_bt_get_symbols(addresses, num_frames) NULL
00041 #endif
00042 
00043 /* \brief
00044  *
00045  * A structure to hold backtrace information. This structure provides an easy means to
00046  * store backtrace information or pass backtraces to other functions.
00047  */
00048 struct ast_bt {
00049    /*! The addresses of the stack frames. This is filled in by calling the glibc backtrace() function */
00050    void *addresses[AST_MAX_BT_FRAMES];
00051    /*! The number of stack frames in the backtrace */
00052    int num_frames;
00053    /*! Tells if the ast_bt structure was dynamically allocated */
00054    unsigned int alloced:1;
00055 };
00056 
00057 #ifdef HAVE_BKTR
00058 
00059 /* \brief
00060  * Allocates memory for an ast_bt and stores addresses and symbols.
00061  *
00062  * \return Returns NULL on failure, or the allocated ast_bt on success
00063  * \since 1.6.1
00064  */
00065 struct ast_bt *__ast_bt_create(void);
00066 
00067 /* \brief
00068  * Fill an allocated ast_bt with addresses
00069  *
00070  * \retval 0 Success
00071  * \retval -1 Failure
00072  * \since 1.6.1
00073  */
00074 int __ast_bt_get_addresses(struct ast_bt *bt);
00075 
00076 /* \brief
00077  *
00078  * Free dynamically allocated portions of an ast_bt
00079  *
00080  * \retval NULL.
00081  * \since 1.6.1
00082  */
00083 void *__ast_bt_destroy(struct ast_bt *bt);
00084 
00085 /* \brief Retrieve symbols for a set of backtrace addresses
00086  *
00087  * \param addresses A list of addresses, such as the ->addresses structure element of struct ast_bt.
00088  * \param num_frames Number of addresses in the addresses list
00089  * \retval NULL Unable to allocate memory
00090  * \return List of strings. Free the entire list with a single ast_std_free call.
00091  * \since 1.6.2.16
00092  */
00093 char **__ast_bt_get_symbols(void **addresses, size_t num_frames);
00094 
00095 #endif /* HAVE_BKTR */
00096 
00097 #endif /* BACKTRACE_H_ */

Generated on Thu Apr 16 06:27:15 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6