libsanitizer/include/sanitizer/asan_interface.h

   1 //===-- sanitizer/asan_interface.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 // This file is a part of AddressSanitizer, an address sanity checker.
   9 //
  10 // This header can be included by the instrumented program to fetch
  11 // data (mostly allocator statistics) from ASan runtime library.
  12 //===----------------------------------------------------------------------===//
  13 #ifndef SANITIZER_ASAN_INTERFACE_H
  14 #define SANITIZER_ASAN_INTERFACE_H
  15
  16 #include <sanitizer/common_interface_defs.h>
  17
  18 // ----------- ATTENTION -------------
  19 // This header should NOT include any other headers from ASan runtime.
  20 // All functions in this header are extern "C" and start with __asan_.
  21
  22 using __sanitizer::uptr;
  23
  24 extern "C" {
  25   // This function should be called at the very beginning of the process,
  26   // before any instrumented code is executed and before any call to malloc.
  27   void __asan_init() SANITIZER_INTERFACE_ATTRIBUTE;
  28
  29   // This function should be called by the instrumented code.
  30   // 'addr' is the address of a global variable called 'name' of 'size' bytes.
  31   void __asan_register_global(uptr addr, uptr size, const char *name)
  32       SANITIZER_INTERFACE_ATTRIBUTE;
  33
  34   // This structure describes an instrumented global variable.
  35   struct __asan_global {
  36     uptr beg;                // The address of the global.
  37     uptr size;               // The original size of the global.
  38     uptr size_with_redzone;  // The size with the redzone.
  39     const char *name;        // Name as a C string.
  40     uptr has_dynamic_init;   // Non-zero if the global has dynamic initializer.
  41   };
  42
  43   // These two functions should be called by the instrumented code.
  44   // 'globals' is an array of structures describing 'n' globals.
  45   void __asan_register_globals(__asan_global *globals, uptr n)
  46       SANITIZER_INTERFACE_ATTRIBUTE;
  47   void __asan_unregister_globals(__asan_global *globals, uptr n)
  48       SANITIZER_INTERFACE_ATTRIBUTE;
  49
  50   // These two functions should be called before and after dynamic initializers
  51   // run, respectively.  They should be called with parameters describing all
  52   // dynamically initialized globals defined in the calling TU.
  53   void __asan_before_dynamic_init(uptr first_addr, uptr last_addr)
  54       SANITIZER_INTERFACE_ATTRIBUTE;
  55   void __asan_after_dynamic_init()
  56       SANITIZER_INTERFACE_ATTRIBUTE;
  57
  58   // These two functions are used by the instrumented code in the
  59   // use-after-return mode. __asan_stack_malloc allocates size bytes of
  60   // fake stack and __asan_stack_free poisons it. real_stack is a pointer to
  61   // the real stack region.
  62   uptr __asan_stack_malloc(uptr size, uptr real_stack)
  63       SANITIZER_INTERFACE_ATTRIBUTE;
  64   void __asan_stack_free(uptr ptr, uptr size, uptr real_stack)
  65       SANITIZER_INTERFACE_ATTRIBUTE;
  66
  67   // Marks memory region [addr, addr+size) as unaddressable.
  68   // This memory must be previously allocated by the user program. Accessing
  69   // addresses in this region from instrumented code is forbidden until
  70   // this region is unpoisoned. This function is not guaranteed to poison
  71   // the whole region - it may poison only subregion of [addr, addr+size) due
  72   // to ASan alignment restrictions.
  73   // Method is NOT thread-safe in the sense that no two threads can
  74   // (un)poison memory in the same memory region simultaneously.
  75   void __asan_poison_memory_region(void const volatile *addr, uptr size)
  76       SANITIZER_INTERFACE_ATTRIBUTE;
  77   // Marks memory region [addr, addr+size) as addressable.
  78   // This memory must be previously allocated by the user program. Accessing
  79   // addresses in this region is allowed until this region is poisoned again.
  80   // This function may unpoison a superregion of [addr, addr+size) due to
  81   // ASan alignment restrictions.
  82   // Method is NOT thread-safe in the sense that no two threads can
  83   // (un)poison memory in the same memory region simultaneously.
  84   void __asan_unpoison_memory_region(void const volatile *addr, uptr size)
  85       SANITIZER_INTERFACE_ATTRIBUTE;
  86
  87   // Performs cleanup before a NoReturn function. Must be called before things
  88   // like _exit and execl to avoid false positives on stack.
  89   void __asan_handle_no_return() SANITIZER_INTERFACE_ATTRIBUTE;
  90
  91 // User code should use macro instead of functions.
  92 #if __has_feature(address_sanitizer)
  93 #define ASAN_POISON_MEMORY_REGION(addr, size) \
  94   __asan_poison_memory_region((addr), (size))
  95 #define ASAN_UNPOISON_MEMORY_REGION(addr, size) \
  96   __asan_unpoison_memory_region((addr), (size))
  97 #else
  98 #define ASAN_POISON_MEMORY_REGION(addr, size) \
  99   ((void)(addr), (void)(size))
 100 #define ASAN_UNPOISON_MEMORY_REGION(addr, size) \
 101   ((void)(addr), (void)(size))
 102 #endif
 103
 104   // Returns true iff addr is poisoned (i.e. 1-byte read/write access to this
 105   // address will result in error report from AddressSanitizer).
 106   bool __asan_address_is_poisoned(void const volatile *addr)
 107       SANITIZER_INTERFACE_ATTRIBUTE;
 108
 109   // This is an internal function that is called to report an error.
 110   // However it is still a part of the interface because users may want to
 111   // set a breakpoint on this function in a debugger.
 112   void __asan_report_error(uptr pc, uptr bp, uptr sp,
 113                            uptr addr, bool is_write, uptr access_size)
 114     SANITIZER_INTERFACE_ATTRIBUTE;
 115
 116   // Sets the exit code to use when reporting an error.
 117   // Returns the old value.
 118   int __asan_set_error_exit_code(int exit_code)
 119       SANITIZER_INTERFACE_ATTRIBUTE;
 120
 121   // Sets the callback to be called right before death on error.
 122   // Passing 0 will unset the callback.
 123   void __asan_set_death_callback(void (*callback)(void))
 124       SANITIZER_INTERFACE_ATTRIBUTE;
 125
 126   void __asan_set_error_report_callback(void (*callback)(const char*))
 127       SANITIZER_INTERFACE_ATTRIBUTE;
 128
 129   // User may provide function that would be called right when ASan detects
 130   // an error. This can be used to notice cases when ASan detects an error, but
 131   // the program crashes before ASan report is printed.
 132   void __asan_on_error()
 133       SANITIZER_WEAK_ATTRIBUTE SANITIZER_INTERFACE_ATTRIBUTE;
 134
 135   // User may provide its own implementation for symbolization function.
 136   // It should print the description of instruction at address "pc" to
 137   // "out_buffer". Description should be at most "out_size" bytes long.
 138   // User-specified function should return true if symbolization was
 139   // successful.
 140   bool __asan_symbolize(const void *pc, char *out_buffer, int out_size)
 141       SANITIZER_WEAK_ATTRIBUTE SANITIZER_INTERFACE_ATTRIBUTE;
 142
 143   // Returns the estimated number of bytes that will be reserved by allocator
 144   // for request of "size" bytes. If ASan allocator can't allocate that much
 145   // memory, returns the maximal possible allocation size, otherwise returns
 146   // "size".
 147   uptr __asan_get_estimated_allocated_size(uptr size)
 148       SANITIZER_INTERFACE_ATTRIBUTE;
 149   // Returns true if p was returned by the ASan allocator and
 150   // is not yet freed.
 151   bool __asan_get_ownership(const void *p)
 152       SANITIZER_INTERFACE_ATTRIBUTE;
 153   // Returns the number of bytes reserved for the pointer p.
 154   // Requires (get_ownership(p) == true) or (p == 0).
 155   uptr __asan_get_allocated_size(const void *p)
 156       SANITIZER_INTERFACE_ATTRIBUTE;
 157   // Number of bytes, allocated and not yet freed by the application.
 158   uptr __asan_get_current_allocated_bytes()
 159       SANITIZER_INTERFACE_ATTRIBUTE;
 160   // Number of bytes, mmaped by asan allocator to fulfill allocation requests.
 161   // Generally, for request of X bytes, allocator can reserve and add to free
 162   // lists a large number of chunks of size X to use them for future requests.
 163   // All these chunks count toward the heap size. Currently, allocator never
 164   // releases memory to OS (instead, it just puts freed chunks to free lists).
 165   uptr __asan_get_heap_size()
 166       SANITIZER_INTERFACE_ATTRIBUTE;
 167   // Number of bytes, mmaped by asan allocator, which can be used to fulfill
 168   // allocation requests. When a user program frees memory chunk, it can first
 169   // fall into quarantine and will count toward __asan_get_free_bytes() later.
 170   uptr __asan_get_free_bytes()
 171       SANITIZER_INTERFACE_ATTRIBUTE;
 172   // Number of bytes in unmapped pages, that are released to OS. Currently,
 173   // always returns 0.
 174   uptr __asan_get_unmapped_bytes()
 175       SANITIZER_INTERFACE_ATTRIBUTE;
 176   // Prints accumulated stats to stderr. Used for debugging.
 177   void __asan_print_accumulated_stats()
 178       SANITIZER_INTERFACE_ATTRIBUTE;
 179
 180   // This function may be overriden by user to provide a string containing
 181   // ASan runtime options. See asan_flags.h for details.
 182   const char* __asan_default_options()
 183       SANITIZER_WEAK_ATTRIBUTE SANITIZER_INTERFACE_ATTRIBUTE;
 184
 185   // Malloc hooks that may be overriden by user.
 186   // __asan_malloc_hook(ptr, size) is called immediately after
 187   //   allocation of "size" bytes, which returned "ptr".
 188   // __asan_free_hook(ptr) is called immediately before
 189   //   deallocation of "ptr".
 190   // If user doesn't provide implementations of these hooks, they are no-op.
 191   void __asan_malloc_hook(void *ptr, uptr size)
 192       SANITIZER_WEAK_ATTRIBUTE SANITIZER_INTERFACE_ATTRIBUTE;
 193   void __asan_free_hook(void *ptr)
 194       SANITIZER_WEAK_ATTRIBUTE SANITIZER_INTERFACE_ATTRIBUTE;
 195 }  // extern "C"
 196
 197 #endif  // SANITIZER_ASAN_INTERFACE_H