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-2021 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 
86 /*!
87  * Demangle a backtrace description structure (for C++).
88  *
89  * parameters:
90  *   bt: <-> pointer to backtrace description structure.
91  */
92 
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__ */
190