backtrace: Refactor ast_bt_get_symbols so it doesn't crash
[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 #define ast_bt_free_symbols(string_vector) __ast_bt_free_symbols((string_vector))
37 #else
38 #define ast_bt_get_addresses(bt) 0
39 #define ast_bt_create() NULL
40 #define ast_bt_destroy(bt) NULL
41 #define ast_bt_get_symbols(addresses, num_frames) NULL
42 #define ast_bt_free_symbols(string_vector) NULL
43 #endif
44
45 /* \brief
46  *
47  * A structure to hold backtrace information. This structure provides an easy means to
48  * store backtrace information or pass backtraces to other functions.
49  */
50 struct ast_bt {
51         /*! The addresses of the stack frames. This is filled in by calling the glibc backtrace() function */
52         void *addresses[AST_MAX_BT_FRAMES];
53         /*! The number of stack frames in the backtrace */
54         int num_frames;
55         /*! Tells if the ast_bt structure was dynamically allocated */
56         unsigned int alloced:1;
57 };
58
59 #ifdef HAVE_BKTR
60
61 /* \brief
62  * Allocates memory for an ast_bt and stores addresses and symbols.
63  *
64  * \return Returns NULL on failure, or the allocated ast_bt on success
65  * \since 1.6.1
66  */
67 struct ast_bt *__ast_bt_create(void);
68
69 /* \brief
70  * Fill an allocated ast_bt with addresses
71  *
72  * \retval 0 Success
73  * \retval -1 Failure
74  * \since 1.6.1
75  */
76 int __ast_bt_get_addresses(struct ast_bt *bt);
77
78 /* \brief
79  *
80  * Free dynamically allocated portions of an ast_bt
81  *
82  * \retval NULL.
83  * \since 1.6.1
84  */
85 void *__ast_bt_destroy(struct ast_bt *bt);
86
87 /* \brief Retrieve symbols for a set of backtrace addresses
88  *
89  * \param addresses A list of addresses, such as the ->addresses structure element of struct ast_bt.
90  * \param num_frames Number of addresses in the addresses list
91  *
92  * \retval NULL Unable to allocate memory
93  * \return Vector of strings. Free with ast_bt_free_symbols
94  *
95  * \note The first frame in the addresses array will usually point to __ast_bt_create
96  * so when printing the symbols you may wish to start at position 1 rather than 0.
97  *
98  * \since 1.6.2.16
99  */
100 struct ast_vector_string *__ast_bt_get_symbols(void **addresses, size_t num_frames);
101
102 /* \brief Free symbols returned from ast_bt_get_symbols
103  *
104  * \param symbols The symbol string vector
105  *
106  * \since 13.24.0
107  */
108 void __ast_bt_free_symbols(struct ast_vector_string *symbols);
109
110 #endif /* HAVE_BKTR */
111
112 #endif /* BACKTRACE_H_ */