src/bft/bft_backtrace.h Source File

| programmer's documentation

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
bft_backtrace.h
Go to the documentation of this file.
1 #ifndef __BFT_BACKTRACE_H__
2 #define __BFT_BACKTRACE_H__
3
4 /*============================================================================
5 * Obtaining a stack backtrace
6 *============================================================================*/
7
8 /*
9 This file is part of Code_Saturne, a general-purpose CFD tool.
10
11 Copyright (C) 1998-2013 EDF S.A.
12
13 This program is free software; you can redistribute it and/or modify it under
14 the terms of the GNU General Public License as published by the Free Software
15 Foundation; either version 2 of the License, or (at your option) any later
16 version.
17
18 This program is distributed in the hope that it will be useful, but WITHOUT
19 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
21 details.
22
23 You should have received a copy of the GNU General Public License along with
24 this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
25 Street, Fifth Floor, Boston, MA 02110-1301, USA.
26 */
27
28 /*----------------------------------------------------------------------------*/
29
30 #include "cs_defs.h"
31
32 /*----------------------------------------------------------------------------
33 * Standard C library headers
34 *----------------------------------------------------------------------------*/
35
36 #include <stdarg.h>
37
38 /*----------------------------------------------------------------------------
39 * Local headers
40 *----------------------------------------------------------------------------*/
41
42 /*-----------------------------------------------------------------------------*/
43
44 BEGIN_C_DECLS
45
46 /*============================================================================
47 * Public types
48 *============================================================================*/
49
50 /* BFT backtrace descriptor */
51
52 typedef struct _bft_backtrace_t bft_backtrace_t;
53
54 /* Pointers for backtrace print functions */
55
56 typedef void (bft_backtrace_print_t) (int start_depth);
57
58 /*============================================================================
59 * Public function prototypes
60 *============================================================================*/
61
62 /*
63 * Build a backtrace description structure.
64 *
65 * returns:
66 * pointer to bft_backtrace_t backtrace descriptor (NULL in case of
67 * error, or if backtracing is unavailable on this architecture).
68 */
69
70 bft_backtrace_t *
71 bft_backtrace_create(void);
72
73 /*
74 * Free a backtrace description structure.
75 *
76 * parameters:
77 * bt: <-> pointer to backtrace description structure.
78 *
79 * returns:
80 * NULL pointer.
81 */
82
83 bft_backtrace_t *
84 bft_backtrace_destroy(bft_backtrace_t *bt);
85
93 void
94 bft_backtrace_demangle(bft_backtrace_t *bt);
95
96 /*
97 * Return the total depth of a backtrace.
98 *
99 * parameters:
100 * bt: <-- pointer to backtrace description structure.
101 *
102 * returns:
103 * total backtrace depth.
104 */
105
106 int
107 bft_backtrace_size(const bft_backtrace_t *bt);
108
109 /*
110 * Return file name associated with a backtrace at a given depth.
111 *
112 * parameters:
113 * bt: <-- pointer to backtrace description structure.
114 * depth: <-- index in backtrace structure (< bft_backtrace_size(bt)).
115 *
116 * returns:
117 * file name at the given depth, or NULL.
118 */
119
120 const char *
121 bft_backtrace_file(bft_backtrace_t *bt,
122 int depth);
123
124 /*
125 * Return function name associated with a backtrace at a given depth.
126 *
127 * parameters:
128 * bt: <-- pointer to backtrace description structure.
129 * depth: <-- index in backtrace structure (< bft_backtrace_size(bt)).
130 *
131 * returns:
132 * function name at the given depth, or NULL.
133 */
134
135 const char *
136 bft_backtrace_function(bft_backtrace_t *bt,
137 int depth);
138
139 /*
140 * Return address associated with a backtrace at a given depth.
141 *
142 * parameters:
143 * bt: <-- pointer to backtrace description structure.
144 * depth: <-- index in backtrace structure (< bft_backtrace_size(bt)).
145 *
146 * returns:
147 * address at the given depth, or NULL.
148 */
149
150 const char *
151 bft_backtrace_address(bft_backtrace_t *bt,
152 int depth);
153
154 /*
155 * Print a backtrace.
156 *
157 * parameters:
158 * start_depth: <-- depth of backtrace at which to start printing
159 * (0 for all, including backtrace print function)
160 */
161
162 void
163 bft_backtrace_print(int start_depth);
164
165 /*
166 * Returns backtrace print function.
167 *
168 * returns:
169 * pointer to the backtrace print function.
170 */
171
172 bft_backtrace_print_t *
173 bft_backtrace_print_get(void);
174
175 /*
176 * Sets a backtrace print function.
177 *
178 * parameters:
179 * fct: <-- pointer to a bft_backtrace_print_t type function.
180 */
181
182 void
183 bft_backtrace_print_set(bft_backtrace_print_t *const fct);
184
185 /*----------------------------------------------------------------------------*/
186
187 END_C_DECLS
188
189 #endif /* __BFT_BACKTRACE_H__ */