libbacktrace/internal.h

   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.  */
 196
 197 extern void backtrace_vector_finish (struct backtrace_state *state,
 198                                      struct backtrace_vector *vec);
 199
 200 /* Release any extra space allocated for VEC.  Returns 1 on success, 0
 201    on failure.  */
 202
 203 extern int backtrace_vector_release (struct backtrace_state *state,
 204                                      struct backtrace_vector *vec,
 205                                      backtrace_error_callback error_callback,
 206                                      void *data);
 207
 208 /* Read initial debug data from a descriptor, and set the
 209    fileline_data, syminfo_fn, and syminfo_data fields of STATE.
 210    Return the fileln_fn field in *FILELN_FN--this is done this way so
 211    that the synchronization code is only implemented once.  This is
 212    called after the descriptor has first been opened.  It will close
 213    the descriptor if it is no longer needed.  Returns 1 on success, 0
 214    on error.  There will be multiple implementations of this function,
 215    for different file formats.  Each system will compile the
 216    appropriate one.  */
 217
 218 extern int backtrace_initialize (struct backtrace_state *state,
 219                                  int descriptor,
 220                                  backtrace_error_callback error_callback,
 221                                  void *data,
 222                                  fileline *fileline_fn);
 223
 224 /* Add file/line information for a DWARF module.  */
 225
 226 extern int backtrace_dwarf_add (struct backtrace_state *state,
 227                                 uintptr_t base_address,
 228                                 const unsigned char* dwarf_info,
 229                                 size_t dwarf_info_size,
 230                                 const unsigned char *dwarf_line,
 231                                 size_t dwarf_line_size,
 232                                 const unsigned char *dwarf_abbrev,
 233                                 size_t dwarf_abbrev_size,
 234                                 const unsigned char *dwarf_ranges,
 235                                 size_t dwarf_range_size,
 236                                 const unsigned char *dwarf_str,
 237                                 size_t dwarf_str_size,
 238                                 int is_bigendian,
 239                                 backtrace_error_callback error_callback,
 240                                 void *data, fileline *fileline_fn);
 241
 242 #endif