libsanitizer/sanitizer_common/sanitizer_symbolizer.h

   1 //===-- sanitizer_symbolizer.h ----------------------------------*- C++ -*-===//
   2 //
   3 // This file is distributed under the University of Illinois Open Source
   4 // License. See LICENSE.TXT for details.
   5 //
   6 //===----------------------------------------------------------------------===//
   7 //
   8 // Symbolizer is used by sanitizers to map instruction address to a location in
   9 // source code at run-time. Symbolizer either uses __sanitizer_symbolize_*
  10 // defined in the program, or (if they are missing) tries to find and
  11 // launch "llvm-symbolizer" commandline tool in a separate process and
  12 // communicate with it.
  13 //
  14 // Generally we should try to avoid calling system library functions during
  15 // symbolization (and use their replacements from sanitizer_libc.h instead).
  16 //===----------------------------------------------------------------------===//
  17 #ifndef SANITIZER_SYMBOLIZER_H
  18 #define SANITIZER_SYMBOLIZER_H
  19
  20 #include "sanitizer_allocator_internal.h"
  21 #include "sanitizer_internal_defs.h"
  22 #include "sanitizer_libc.h"
  23
  24 namespace __sanitizer {
  25
  26 struct AddressInfo {
  27   uptr address;
  28
  29   char *module;
  30   uptr module_offset;
  31
  32   static const uptr kUnknown = ~(uptr)0;
  33   char *function;
  34   uptr function_offset;
  35
  36   char *file;
  37   int line;
  38   int column;
  39
  40   AddressInfo() {
  41     internal_memset(this, 0, sizeof(AddressInfo));
  42     function_offset = kUnknown;
  43   }
  44
  45   // Deletes all strings and resets all fields.
  46   void Clear() {
  47     InternalFree(module);
  48     InternalFree(function);
  49     InternalFree(file);
  50     internal_memset(this, 0, sizeof(AddressInfo));
  51     function_offset = kUnknown;
  52   }
  53
  54   void FillAddressAndModuleInfo(uptr addr, const char *mod_name,
  55                                 uptr mod_offset) {
  56     address = addr;
  57     module = internal_strdup(mod_name);
  58     module_offset = mod_offset;
  59   }
  60 };
  61
  62 struct DataInfo {
  63   uptr address;
  64   char *module;
  65   uptr module_offset;
  66   char *name;
  67   uptr start;
  68   uptr size;
  69 };
  70
  71 class Symbolizer {
  72  public:
  73   /// Returns platform-specific implementation of Symbolizer. The symbolizer
  74   /// must be initialized (with init or disable) before calling this function.
  75   static Symbolizer *Get();
  76   /// Returns platform-specific implementation of Symbolizer, or null if not
  77   /// initialized.
  78   static Symbolizer *GetOrNull();
  79   /// Returns platform-specific implementation of Symbolizer.  Will
  80   /// automatically initialize symbolizer as if by calling Init(0) if needed.
  81   static Symbolizer *GetOrInit();
  82   /// Initialize and return the symbolizer, given an optional path to an
  83   /// external symbolizer.  The path argument is only required for legacy
  84   /// reasons as this function will check $PATH for an external symbolizer.  Not
  85   /// thread safe.
  86   static Symbolizer *Init(const char* path_to_external = 0);
  87   // Fills at most "max_frames" elements of "frames" with descriptions
  88   // for a given address (in all inlined functions). Returns the number
  89   // of descriptions actually filled.
  90   virtual uptr SymbolizePC(uptr address, AddressInfo *frames, uptr max_frames) {
  91     return 0;
  92   }
  93   virtual bool SymbolizeData(uptr address, DataInfo *info) {
  94     return false;
  95   }
  96   virtual bool GetModuleNameAndOffsetForPC(uptr pc, const char **module_name,
  97                                            uptr *module_address) {
  98     return false;
  99   }
 100   virtual bool CanReturnFileLineInfo() {
 101     return false;
 102   }
 103   // Release internal caches (if any).
 104   virtual void Flush() {}
 105   // Attempts to demangle the provided C++ mangled name.
 106   virtual const char *Demangle(const char *name) {
 107     return name;
 108   }
 109   virtual void PrepareForSandboxing() {}
 110
 111   // Allow user to install hooks that would be called before/after Symbolizer
 112   // does the actual file/line info fetching. Specific sanitizers may need this
 113   // to distinguish system library calls made in user code from calls made
 114   // during in-process symbolization.
 115   typedef void (*StartSymbolizationHook)();
 116   typedef void (*EndSymbolizationHook)();
 117   // May be called at most once.
 118   void AddHooks(StartSymbolizationHook start_hook,
 119                 EndSymbolizationHook end_hook);
 120
 121  private:
 122   /// Platform-specific function for creating a Symbolizer object.
 123   static Symbolizer *PlatformInit(const char *path_to_external);
 124   /// Create a symbolizer and store it to symbolizer_ without checking if one
 125   /// already exists.  Not thread safe.
 126   static Symbolizer *CreateAndStore(const char *path_to_external);
 127   /// Initialize the symbolizer in a disabled state.  Not thread safe.
 128   static Symbolizer *Disable();
 129
 130   static Symbolizer *symbolizer_;
 131   static StaticSpinMutex init_mu_;
 132
 133  protected:
 134   Symbolizer();
 135
 136   static LowLevelAllocator symbolizer_allocator_;
 137
 138   StartSymbolizationHook start_hook_;
 139   EndSymbolizationHook end_hook_;
 140   class SymbolizerScope {
 141    public:
 142     explicit SymbolizerScope(const Symbolizer *sym);
 143     ~SymbolizerScope();
 144    private:
 145     const Symbolizer *sym_;
 146   };
 147 };
 148
 149 }  // namespace __sanitizer
 150
 151 #endif  // SANITIZER_SYMBOLIZER_H