1 /* internal.h -- Internal header file for stack backtrace library. 2 Copyright (C) 2012-2013 Free Software Foundation, Inc. 3 Written by Ian Lance Taylor, Google. 4 5 Redistribution and use in source and binary forms, with or without 6 modification, are permitted provided that the following conditions are 7 met: 8 9 (1) Redistributions of source code must retain the above copyright 10 notice, this list of conditions and the following disclaimer. 11 12 (2) Redistributions in binary form must reproduce the above copyright 13 notice, this list of conditions and the following disclaimer in 14 the documentation and/or other materials provided with the 15 distribution. 16 17 (3) The name of the author may not be used to 18 endorse or promote products derived from this software without 19 specific prior written permission. 20 21 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 22 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 23 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, 25 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 26 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 27 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 29 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 30 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31 POSSIBILITY OF SUCH DAMAGE. */ 32 33 #ifndef BACKTRACE_INTERNAL_H 34 #define BACKTRACE_INTERNAL_H 35 36 /* We assume that <sys/types.h> and "backtrace.h" have already been 37 included. */ 38 39 #ifndef GCC_VERSION 40 # define GCC_VERSION (__GNUC__ * 1000 + __GNUC_MINOR__) 41 #endif 42 43 #if (GCC_VERSION < 2007) 44 # define __attribute__(x) 45 #endif 46 47 #ifndef ATTRIBUTE_UNUSED 48 # define ATTRIBUTE_UNUSED __attribute__ ((__unused__)) 49 #endif 50 51 #ifndef ATTRIBUTE_MALLOC 52 # if (GCC_VERSION >= 2096) 53 # define ATTRIBUTE_MALLOC __attribute__ ((__malloc__)) 54 # else 55 # define ATTRIBUTE_MALLOC 56 # endif 57 #endif 58 59 #ifndef HAVE_SYNC_FUNCTIONS 60 61 /* Define out the sync functions. These should never be called if 62 they are not available. */ 63 64 #define __sync_bool_compare_and_swap(A, B, C) (abort(), 1) 65 #define __sync_lock_test_and_set(A, B) (abort(), 0) 66 #define __sync_lock_release(A) abort() 67 68 #endif /* !defined(HAVE_SYNC_FUNCTIONS) */ 69 70 /* The type of the function that collects file/line information. This 71 is like backtrace_pcinfo. */ 72 73 typedef int (*fileline) (struct backtrace_state *state, uintptr_t pc, 74 backtrace_full_callback callback, 75 backtrace_error_callback error_callback, void *data); 76 77 /* The type of the function that collects symbol information. This is 78 like backtrace_syminfo. */ 79 80 typedef void (*syminfo) (struct backtrace_state *state, uintptr_t pc, 81 backtrace_syminfo_callback callback, 82 backtrace_error_callback error_callback, void *data); 83 84 /* What the backtrace state pointer points to. */ 85 86 struct backtrace_state 87 { 88 /* The name of the executable. */ 89 const char *filename; 90 /* Non-zero if threaded. */ 91 int threaded; 92 /* The master lock for fileline_fn, fileline_data, syminfo_fn, 93 syminfo_data, fileline_initialization_failed and everything the 94 data pointers point to. */ 95 void *lock; 96 /* The function that returns file/line information. */ 97 fileline fileline_fn; 98 /* The data to pass to FILELINE_FN. */ 99 void *fileline_data; 100 /* The function that returns symbol information. */ 101 syminfo syminfo_fn; 102 /* The data to pass to SYMINFO_FN. */ 103 void *syminfo_data; 104 /* Whether initializing the file/line information failed. */ 105 int fileline_initialization_failed; 106 /* The lock for the freelist. */ 107 int lock_alloc; 108 /* The freelist when using mmap. */ 109 struct backtrace_freelist_struct *freelist; 110 }; 111 112 /* Open a file for reading. Returns -1 on error. If DOES_NOT_EXIST 113 is not NULL, *DOES_NOT_EXIST will be set to 0 normally and set to 1 114 if the file does not exist. If the file does not exist and 115 DOES_NOT_EXIST is not NULL, the function will return -1 and will 116 not call ERROR_CALLBACK. On other errors, or if DOES_NOT_EXIST is 117 NULL, the function will call ERROR_CALLBACK before returning. */ 118 extern int backtrace_open (const char *filename, 119 backtrace_error_callback error_callback, 120 void *data, 121 int *does_not_exist); 122 123 /* A view of the contents of a file. This supports mmap when 124 available. A view will remain in memory even after backtrace_close 125 is called on the file descriptor from which the view was 126 obtained. */ 127 128 struct backtrace_view 129 { 130 /* The data that the caller requested. */ 131 const void *data; 132 /* The base of the view. */ 133 void *base; 134 /* The total length of the view. */ 135 size_t len; 136 }; 137 138 /* Create a view of SIZE bytes from DESCRIPTOR at OFFSET. Store the 139 result in *VIEW. Returns 1 on success, 0 on error. */ 140 extern int backtrace_get_view (struct backtrace_state *state, int descriptor, 141 off_t offset, size_t size, 142 backtrace_error_callback error_callback, 143 void *data, struct backtrace_view *view); 144 145 /* Release a view created by backtrace_get_view. */ 146 extern void backtrace_release_view (struct backtrace_state *state, 147 struct backtrace_view *view, 148 backtrace_error_callback error_callback, 149 void *data); 150 151 /* Close a file opened by backtrace_open. Returns 1 on success, 0 on 152 error. */ 153 154 extern int backtrace_close (int descriptor, 155 backtrace_error_callback error_callback, 156 void *data); 157 158 /* Allocate memory. This is like malloc. */ 159 160 extern void *backtrace_alloc (struct backtrace_state *state, size_t size, 161 backtrace_error_callback error_callback, 162 void *data) ATTRIBUTE_MALLOC; 163 164 /* Free memory allocated by backtrace_alloc. */ 165 166 extern void backtrace_free (struct backtrace_state *state, void *mem, 167 size_t size, 168 backtrace_error_callback error_callback, 169 void *data); 170 171 /* A growable vector of some struct. This is used for more efficient 172 allocation when we don't know the final size of some group of data 173 that we want to represent as an array. */ 174 175 struct backtrace_vector 176 { 177 /* The base of the vector. */ 178 void *base; 179 /* The number of bytes in the vector. */ 180 size_t size; 181 /* The number of bytes available at the current allocation. */ 182 size_t alc; 183 }; 184 185 /* Grow VEC by SIZE bytes. Return a pointer to the newly allocated 186 bytes. Note that this may move the entire vector to a new memory 187 location. Returns NULL on failure. */ 188 189 extern void *backtrace_vector_grow (struct backtrace_state *state, size_t size, 190 backtrace_error_callback error_callback, 191 void *data, 192 struct backtrace_vector *vec); 193 194 /* Finish the current allocation on VEC. Prepare to start a new 195 allocation. The finished allocation will never be freed. Returns 196 a pointer to the base of the finished entries, or NULL on 197 failure. */ 198 199 extern void* backtrace_vector_finish (struct backtrace_state *state, 200 struct backtrace_vector *vec, 201 backtrace_error_callback error_callback, 202 void *data); 203 204 /* Release any extra space allocated for VEC. This may change 205 VEC->base. Returns 1 on success, 0 on failure. */ 206 207 extern int backtrace_vector_release (struct backtrace_state *state, 208 struct backtrace_vector *vec, 209 backtrace_error_callback error_callback, 210 void *data); 211 212 /* Read initial debug data from a descriptor, and set the 213 fileline_data, syminfo_fn, and syminfo_data fields of STATE. 214 Return the fileln_fn field in *FILELN_FN--this is done this way so 215 that the synchronization code is only implemented once. This is 216 called after the descriptor has first been opened. It will close 217 the descriptor if it is no longer needed. Returns 1 on success, 0 218 on error. There will be multiple implementations of this function, 219 for different file formats. Each system will compile the 220 appropriate one. */ 221 222 extern int backtrace_initialize (struct backtrace_state *state, 223 int descriptor, 224 backtrace_error_callback error_callback, 225 void *data, 226 fileline *fileline_fn); 227 228 /* Add file/line information for a DWARF module. */ 229 230 extern int backtrace_dwarf_add (struct backtrace_state *state, 231 uintptr_t base_address, 232 const unsigned char* dwarf_info, 233 size_t dwarf_info_size, 234 const unsigned char *dwarf_line, 235 size_t dwarf_line_size, 236 const unsigned char *dwarf_abbrev, 237 size_t dwarf_abbrev_size, 238 const unsigned char *dwarf_ranges, 239 size_t dwarf_range_size, 240 const unsigned char *dwarf_str, 241 size_t dwarf_str_size, 242 int is_bigendian, 243 backtrace_error_callback error_callback, 244 void *data, fileline *fileline_fn); 245 246 #endif 247