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