libbacktrace/internal.h

   1 /* internal.h -- Internal header file for stack backtrace library.
   2    Copyright (C) 2012 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.  */
 113 extern int backtrace_open (const char *filename,
 114                            backtrace_error_callback error_callback,
 115                            void *data);
 116
 117 /* A view of the contents of a file.  This supports mmap when
 118    available.  A view will remain in memory even after backtrace_close
 119    is called on the file descriptor from which the view was
 120    obtained.  */
 121
 122 struct backtrace_view
 123 {
 124   /* The data that the caller requested.  */
 125   const void *data;
 126   /* The base of the view.  */
 127   void *base;
 128   /* The total length of the view.  */
 129   size_t len;
 130 };
 131
 132 /* Create a view of SIZE bytes from DESCRIPTOR at OFFSET.  Store the
 133    result in *VIEW.  Returns 1 on success, 0 on error.  */
 134 extern int backtrace_get_view (struct backtrace_state *state, int descriptor,
 135                                off_t offset, size_t size,
 136                                backtrace_error_callback error_callback,
 137                                void *data, struct backtrace_view *view);
 138
 139 /* Release a view created by backtrace_get_view.  */
 140 extern void backtrace_release_view (struct backtrace_state *state,
 141                                     struct backtrace_view *view,
 142                                     backtrace_error_callback error_callback,
 143                                     void *data);
 144
 145 /* Close a file opened by backtrace_open.  Returns 1 on success, 0 on
 146    error.  */
 147
 148 extern int backtrace_close (int descriptor,
 149                             backtrace_error_callback error_callback,
 150                             void *data);
 151
 152 /* Allocate memory.  This is like malloc.  */
 153
 154 extern void *backtrace_alloc (struct backtrace_state *state, size_t size,
 155                               backtrace_error_callback error_callback,
 156                               void *data) ATTRIBUTE_MALLOC;
 157
 158 /* Free memory allocated by backtrace_alloc.  */
 159
 160 extern void backtrace_free (struct backtrace_state *state, void *mem,
 161                             size_t size,
 162                             backtrace_error_callback error_callback,
 163                             void *data);
 164
 165 /* A growable vector of some struct.  This is used for more efficient
 166    allocation when we don't know the final size of some group of data
 167    that we want to represent as an array.  */
 168
 169 struct backtrace_vector
 170 {
 171   /* The base of the vector.  */
 172   void *base;
 173   /* The number of bytes in the vector.  */
 174   size_t size;
 175   /* The number of bytes available at the current allocation.  */
 176   size_t alc;
 177 };
 178
 179 /* Grow VEC by SIZE bytes.  Return a pointer to the newly allocated
 180    bytes.  Note that this may move the entire vector to a new memory
 181    location.  Returns NULL on failure.  */
 182
 183 extern void *backtrace_vector_grow (struct backtrace_state *state, size_t size,
 184                                     backtrace_error_callback error_callback,
 185                                     void *data,
 186                                     struct backtrace_vector *vec);
 187
 188 /* Finish the current allocation on VEC.  Prepare to start a new
 189    allocation.  The finished allocation will never be freed.  */
 190
 191 extern void backtrace_vector_finish (struct backtrace_state *state,
 192                                      struct backtrace_vector *vec);
 193
 194 /* Release any extra space allocated for VEC.  Returns 1 on success, 0
 195    on failure.  */
 196
 197 extern int backtrace_vector_release (struct backtrace_state *state,
 198                                      struct backtrace_vector *vec,
 199                                      backtrace_error_callback error_callback,
 200                                      void *data);
 201
 202 /* Read initial debug data from a descriptor, and set the
 203    fileline_data, syminfo_fn, and syminfo_data fields of STATE.
 204    Return the fileln_fn field in *FILELN_FN--this is done this way so
 205    that the synchronization code is only implemented once.  This is
 206    called after the descriptor has first been opened.  It will close
 207    the descriptor if it is no longer needed.  Returns 1 on success, 0
 208    on error.  There will be multiple implementations of this function,
 209    for different file formats.  Each system will compile the
 210    appropriate one.  */
 211
 212 extern int backtrace_initialize (struct backtrace_state *state,
 213                                  int descriptor,
 214                                  backtrace_error_callback error_callback,
 215                                  void *data,
 216                                  fileline *fileline_fn);
 217
 218 /* Prepare to read file/line information from DWARF debug data.  */
 219
 220 extern int backtrace_dwarf_initialize (struct backtrace_state *state,
 221                                        const unsigned char* dwarf_info,
 222                                        size_t dwarf_info_size,
 223                                        const unsigned char *dwarf_line,
 224                                        size_t dwarf_line_size,
 225                                        const unsigned char *dwarf_abbrev,
 226                                        size_t dwarf_abbrev_size,
 227                                        const unsigned char *dwarf_ranges,
 228                                        size_t dwarf_range_size,
 229                                        const unsigned char *dwarf_str,
 230                                        size_t dwarf_str_size,
 231                                        int is_bigendian,
 232                                        backtrace_error_callback error_callback,
 233                                        void *data, fileline *fileline_fn);
 234
 235 #endif