Asterisk - The Open Source Telephony Project GIT-master-5782b03
backtrace.h
Go to the documentation of this file.
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 */
50struct ast_bt {
51 /*! The addresses of the stack frames. This is filled in by calling the glibc backtrace() function */
53 /*! The number of stack frames in the backtrace */
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 * \retval NULL on failure
65 * \return the allocated ast_bt on success
66 * \since 1.6.1
67 */
68struct ast_bt *__ast_bt_create(void);
69
70/*! \brief
71 * Fill an allocated ast_bt with addresses
72 *
73 * \retval 0 Success
74 * \retval -1 Failure
75 * \since 1.6.1
76 */
77int __ast_bt_get_addresses(struct ast_bt *bt);
78
79/*! \brief
80 *
81 * Free dynamically allocated portions of an ast_bt
82 *
83 * \since 1.6.1
84 */
85void *__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 */
100struct 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 */
108void __ast_bt_free_symbols(struct ast_vector_string *symbols);
109
110#endif /* HAVE_BKTR */
111
112#endif /* BACKTRACE_H_ */
void * __ast_bt_destroy(struct ast_bt *bt)
Definition: backtrace.c:98
void __ast_bt_free_symbols(struct ast_vector_string *symbols)
Definition: backtrace.c:308
struct ast_bt * __ast_bt_create(void)
Definition: backtrace.c:78
struct ast_vector_string * __ast_bt_get_symbols(void **addresses, size_t num_frames)
Definition: backtrace.c:281
int __ast_bt_get_addresses(struct ast_bt *bt)
Definition: backtrace.c:92
#define AST_MAX_BT_FRAMES
Definition: backtrace.h:29
A structure to hold backtrace information. This structure provides an easy means to store backtrace i...
Definition: backtrace.h:50
void * addresses[AST_MAX_BT_FRAMES]
Definition: backtrace.h:52
unsigned int alloced
Definition: backtrace.h:56
int num_frames
Definition: backtrace.h:54
String vector definitions.
Definition: vector.h:55