95358bfd26d84559605891a786c11bba0c0d5d3d
[asterisk/asterisk.git] / include / asterisk / backtrace.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2013, Digium, Inc.
5  *
6  * Matt Jordan <mjordan@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Asterisk backtrace generation
21  *
22  * This file provides backtrace generation utilities
23  */
24
25
26 #ifndef BACKTRACE_H_
27 #define BACKTRACE_H_
28
29 #define AST_MAX_BT_FRAMES 32
30
31 #ifdef HAVE_BKTR
32 #define ast_bt_get_addresses(bt) __ast_bt_get_addresses((bt))
33 #define ast_bt_create() __ast_bt_create()
34 #define ast_bt_destroy(bt) __ast_bt_destroy((bt))
35 #define ast_bt_get_symbols(addresses, num_frames) __ast_bt_get_symbols((addresses), (num_frames))
36 #else
37 #define ast_bt_get_addresses(bt) 0
38 #define ast_bt_create() NULL
39 #define ast_bt_destroy(bt) NULL
40 #define ast_bt_get_symbols(addresses, num_frames) NULL
41 #endif
42
43 /* \brief
44  *
45  * A structure to hold backtrace information. This structure provides an easy means to
46  * store backtrace information or pass backtraces to other functions.
47  */
48 struct ast_bt {
49         /*! The addresses of the stack frames. This is filled in by calling the glibc backtrace() function */
50         void *addresses[AST_MAX_BT_FRAMES];
51         /*! The number of stack frames in the backtrace */
52         int num_frames;
53         /*! Tells if the ast_bt structure was dynamically allocated */
54         unsigned int alloced:1;
55 };
56
57 #ifdef HAVE_BKTR
58
59 /* \brief
60  * Allocates memory for an ast_bt and stores addresses and symbols.
61  *
62  * \return Returns NULL on failure, or the allocated ast_bt on success
63  * \since 1.6.1
64  */
65 struct ast_bt *__ast_bt_create(void);
66
67 /* \brief
68  * Fill an allocated ast_bt with addresses
69  *
70  * \retval 0 Success
71  * \retval -1 Failure
72  * \since 1.6.1
73  */
74 int __ast_bt_get_addresses(struct ast_bt *bt);
75
76 /* \brief
77  *
78  * Free dynamically allocated portions of an ast_bt
79  *
80  * \retval NULL.
81  * \since 1.6.1
82  */
83 void *__ast_bt_destroy(struct ast_bt *bt);
84
85 /* \brief Retrieve symbols for a set of backtrace addresses
86  *
87  * \param addresses A list of addresses, such as the ->addresses structure element of struct ast_bt.
88  * \param num_frames Number of addresses in the addresses list
89  * \retval NULL Unable to allocate memory
90  * \return List of strings. Free the entire list with a single ast_std_free call.
91  * \since 1.6.2.16
92  */
93 char **__ast_bt_get_symbols(void **addresses, size_t num_frames);
94
95 #endif /* HAVE_BKTR */
96
97 #endif /* BACKTRACE_H_ */