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.
   9 //
  10 // Public interface header.
  11 //===----------------------------------------------------------------------===//
  12 #ifndef SANITIZER_ASAN_INTERFACE_H
  13 #define SANITIZER_ASAN_INTERFACE_H
  14
  15 #include <sanitizer/common_interface_defs.h>
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20   // Marks memory region [addr, addr+size) as unaddressable.
  21   // This memory must be previously allocated by the user program. Accessing
  22   // addresses in this region from instrumented code is forbidden until
  23   // this region is unpoisoned. This function is not guaranteed to poison
  24   // the whole region - it may poison only subregion of [addr, addr+size) due
  25   // to ASan alignment restrictions.
  26   // Method is NOT thread-safe in the sense that no two threads can
  27   // (un)poison memory in the same memory region simultaneously.
  28   void __asan_poison_memory_region(void const volatile *addr, size_t size);
  29   // Marks memory region [addr, addr+size) as addressable.
  30   // This memory must be previously allocated by the user program. Accessing
  31   // addresses in this region is allowed until this region is poisoned again.
  32   // This function may unpoison a superregion of [addr, addr+size) due to
  33   // ASan alignment restrictions.
  34   // Method is NOT thread-safe in the sense that no two threads can
  35   // (un)poison memory in the same memory region simultaneously.
  36   void __asan_unpoison_memory_region(void const volatile *addr, size_t size);
  37
  38 // User code should use macros instead of functions.
  39 #if __has_feature(address_sanitizer) || defined(__SANITIZE_ADDRESS__)
  40 #define ASAN_POISON_MEMORY_REGION(addr, size) \
  41   __asan_poison_memory_region((addr), (size))
  42 #define ASAN_UNPOISON_MEMORY_REGION(addr, size) \
  43   __asan_unpoison_memory_region((addr), (size))
  44 #else
  45 #define ASAN_POISON_MEMORY_REGION(addr, size) \
  46   ((void)(addr), (void)(size))
  47 #define ASAN_UNPOISON_MEMORY_REGION(addr, size) \
  48   ((void)(addr), (void)(size))
  49 #endif
  50
  51   // Returns true iff addr is poisoned (i.e. 1-byte read/write access to this
  52   // address will result in error report from AddressSanitizer).
  53   bool __asan_address_is_poisoned(void const volatile *addr);
  54
  55   // If at least on byte in [beg, beg+size) is poisoned, return the address
  56   // of the first such byte. Otherwise return 0.
  57   void *__asan_region_is_poisoned(void *beg, size_t size);
  58
  59   // Print the description of addr (useful when debugging in gdb).
  60   void __asan_describe_address(void *addr);
  61
  62   // This is an internal function that is called to report an error.
  63   // However it is still a part of the interface because users may want to
  64   // set a breakpoint on this function in a debugger.
  65   void __asan_report_error(void *pc, void *bp, void *sp,
  66                            void *addr, bool is_write, size_t access_size);
  67
  68   // Sets the exit code to use when reporting an error.
  69   // Returns the old value.
  70   int __asan_set_error_exit_code(int exit_code);
  71
  72   // Sets the callback to be called right before death on error.
  73   // Passing 0 will unset the callback.
  74   void __asan_set_death_callback(void (*callback)(void));
  75
  76   void __asan_set_error_report_callback(void (*callback)(const char*));
  77
  78   // User may provide function that would be called right when ASan detects
  79   // an error. This can be used to notice cases when ASan detects an error, but
  80   // the program crashes before ASan report is printed.
  81   void __asan_on_error();
  82
  83   // User may provide its own implementation for symbolization function.
  84   // It should print the description of instruction at address "pc" to
  85   // "out_buffer". Description should be at most "out_size" bytes long.
  86   // User-specified function should return true if symbolization was
  87   // successful.
  88   bool __asan_symbolize(const void *pc, char *out_buffer,
  89                                        int out_size);
  90
  91   // Returns the estimated number of bytes that will be reserved by allocator
  92   // for request of "size" bytes. If ASan allocator can't allocate that much
  93   // memory, returns the maximal possible allocation size, otherwise returns
  94   // "size".
  95   size_t __asan_get_estimated_allocated_size(size_t size);
  96   // Returns true if p was returned by the ASan allocator and
  97   // is not yet freed.
  98   bool __asan_get_ownership(const void *p);
  99   // Returns the number of bytes reserved for the pointer p.
 100   // Requires (get_ownership(p) == true) or (p == 0).
 101   size_t __asan_get_allocated_size(const void *p);
 102   // Number of bytes, allocated and not yet freed by the application.
 103   size_t __asan_get_current_allocated_bytes();
 104   // Number of bytes, mmaped by asan allocator to fulfill allocation requests.
 105   // Generally, for request of X bytes, allocator can reserve and add to free
 106   // lists a large number of chunks of size X to use them for future requests.
 107   // All these chunks count toward the heap size. Currently, allocator never
 108   // releases memory to OS (instead, it just puts freed chunks to free lists).
 109   size_t __asan_get_heap_size();
 110   // Number of bytes, mmaped by asan allocator, which can be used to fulfill
 111   // allocation requests. When a user program frees memory chunk, it can first
 112   // fall into quarantine and will count toward __asan_get_free_bytes() later.
 113   size_t __asan_get_free_bytes();
 114   // Number of bytes in unmapped pages, that are released to OS. Currently,
 115   // always returns 0.
 116   size_t __asan_get_unmapped_bytes();
 117   // Prints accumulated stats to stderr. Used for debugging.
 118   void __asan_print_accumulated_stats();
 119
 120   // This function may be optionally provided by user and should return
 121   // a string containing ASan runtime options. See asan_flags.h for details.
 122   const char* __asan_default_options();
 123
 124   // Malloc hooks that may be optionally provided by user.
 125   // __asan_malloc_hook(ptr, size) is called immediately after
 126   //   allocation of "size" bytes, which returned "ptr".
 127   // __asan_free_hook(ptr) is called immediately before
 128   //   deallocation of "ptr".
 129   void __asan_malloc_hook(void *ptr, size_t size);
 130   void __asan_free_hook(void *ptr);
 131 #ifdef __cplusplus
 132 }  // extern "C"
 133 #endif
 134
 135 #endif  // SANITIZER_ASAN_INTERFACE_H