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   char *module;
  29   uptr module_offset;
  30   char *function;
  31   char *file;
  32   int line;
  33   int column;
  34
  35   AddressInfo() {
  36     internal_memset(this, 0, sizeof(AddressInfo));
  37   }
  38
  39   // Deletes all strings and sets all fields to zero.
  40   void Clear() {
  41     InternalFree(module);
  42     InternalFree(function);
  43     InternalFree(file);
  44     internal_memset(this, 0, sizeof(AddressInfo));
  45   }
  46
  47   void FillAddressAndModuleInfo(uptr addr, const char *mod_name,
  48                                 uptr mod_offset) {
  49     address = addr;
  50     module = internal_strdup(mod_name);
  51     module_offset = mod_offset;
  52   }
  53 };
  54
  55 struct DataInfo {
  56   uptr address;
  57   char *module;
  58   uptr module_offset;
  59   char *name;
  60   uptr start;
  61   uptr size;
  62 };
  63
  64 class Symbolizer {
  65  public:
  66   /// Returns platform-specific implementation of Symbolizer. The symbolizer
  67   /// must be initialized (with init or disable) before calling this function.
  68   static Symbolizer *Get();
  69   /// Returns platform-specific implementation of Symbolizer, or null if not
  70   /// initialized.
  71   static Symbolizer *GetOrNull();
  72   /// Returns platform-specific implementation of Symbolizer.  Will
  73   /// automatically initialize symbolizer as if by calling Init(0) if needed.
  74   static Symbolizer *GetOrInit();
  75   /// Initialize and return the symbolizer, given an optional path to an
  76   /// external symbolizer.  The path argument is only required for legacy
  77   /// reasons as this function will check $PATH for an external symbolizer.  Not
  78   /// thread safe.
  79   static Symbolizer *Init(const char* path_to_external = 0);
  80   /// Initialize the symbolizer in a disabled state.  Not thread safe.
  81   static Symbolizer *Disable();
  82   // Fills at most "max_frames" elements of "frames" with descriptions
  83   // for a given address (in all inlined functions). Returns the number
  84   // of descriptions actually filled.
  85   virtual uptr SymbolizeCode(uptr address, AddressInfo *frames,
  86                              uptr max_frames) {
  87     return 0;
  88   }
  89   virtual bool SymbolizeData(uptr address, DataInfo *info) {
  90     return false;
  91   }
  92   virtual bool IsAvailable() {
  93     return false;
  94   }
  95   virtual bool IsExternalAvailable() {
  96     return false;
  97   }
  98   // Release internal caches (if any).
  99   virtual void Flush() {}
 100   // Attempts to demangle the provided C++ mangled name.
 101   virtual const char *Demangle(const char *name) {
 102     return name;
 103   }
 104   virtual void PrepareForSandboxing() {}
 105
 106   // Allow user to install hooks that would be called before/after Symbolizer
 107   // does the actual file/line info fetching. Specific sanitizers may need this
 108   // to distinguish system library calls made in user code from calls made
 109   // during in-process symbolization.
 110   typedef void (*StartSymbolizationHook)();
 111   typedef void (*EndSymbolizationHook)();
 112   // May be called at most once.
 113   void AddHooks(StartSymbolizationHook start_hook,
 114                 EndSymbolizationHook end_hook);
 115
 116  private:
 117   /// Platform-specific function for creating a Symbolizer object.
 118   static Symbolizer *PlatformInit(const char *path_to_external);
 119   /// Create a symbolizer and store it to symbolizer_ without checking if one
 120   /// already exists.  Not thread safe.
 121   static Symbolizer *CreateAndStore(const char *path_to_external);
 122
 123   static Symbolizer *symbolizer_;
 124   static StaticSpinMutex init_mu_;
 125
 126  protected:
 127   Symbolizer();
 128
 129   static LowLevelAllocator symbolizer_allocator_;
 130
 131   StartSymbolizationHook start_hook_;
 132   EndSymbolizationHook end_hook_;
 133   class SymbolizerScope {
 134    public:
 135     explicit SymbolizerScope(const Symbolizer *sym);
 136     ~SymbolizerScope();
 137    private:
 138     const Symbolizer *sym_;
 139   };
 140 };
 141
 142 }  // namespace __sanitizer
 143
 144 #endif  // SANITIZER_SYMBOLIZER_H