compiler-rt/include/sanitizer/asan_interface.h

   1 //===-- sanitizer/asan_interface.h ------------------------------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 // This file is a part of AddressSanitizer (ASan).
  10 //
  11 // Public interface header.
  12 //===----------------------------------------------------------------------===//
  13 #ifndef SANITIZER_ASAN_INTERFACE_H
  14 #define SANITIZER_ASAN_INTERFACE_H
  15
  16 #include <sanitizer/common_interface_defs.h>
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21 /// Marks a memory region (<c>[addr, addr+size)</c>) as unaddressable.
  22 ///
  23 /// This memory must be previously allocated by your program. Instrumented
  24 /// code is forbidden from accessing addresses in this region until it is
  25 /// unpoisoned. This function is not guaranteed to poison the entire region -
  26 /// it could poison only a subregion of <c>[addr, addr+size)</c> due to ASan
  27 /// alignment restrictions.
  28 ///
  29 /// \note This function is not thread-safe because no two threads can poison or
  30 /// unpoison memory in the same memory region simultaneously.
  31 ///
  32 /// \param addr Start of memory region.
  33 /// \param size Size of memory region.
  34 void SANITIZER_CDECL __asan_poison_memory_region(void const volatile *addr,
  35                                                  size_t size);
  36
  37 /// Marks a memory region (<c>[addr, addr+size)</c>) as addressable.
  38 ///
  39 /// This memory must be previously allocated by your program. Accessing
  40 /// addresses in this region is allowed until this region is poisoned again.
  41 /// This function could unpoison a super-region of <c>[addr, addr+size)</c> due
  42 /// to ASan alignment restrictions.
  43 ///
  44 /// \note This function is not thread-safe because no two threads can
  45 /// poison or unpoison memory in the same memory region simultaneously.
  46 ///
  47 /// \param addr Start of memory region.
  48 /// \param size Size of memory region.
  49 void SANITIZER_CDECL __asan_unpoison_memory_region(void const volatile *addr,
  50                                                    size_t size);
  51
  52 // Macros provided for convenience.
  53 #if __has_feature(address_sanitizer) || defined(__SANITIZE_ADDRESS__)
  54 /// Marks a memory region as unaddressable.
  55 ///
  56 /// \note Macro provided for convenience; defined as a no-op if ASan is not
  57 /// enabled.
  58 ///
  59 /// \param addr Start of memory region.
  60 /// \param size Size of memory region.
  61 #define ASAN_POISON_MEMORY_REGION(addr, size)                                  \
  62   __asan_poison_memory_region((addr), (size))
  63
  64 /// Marks a memory region as addressable.
  65 ///
  66 /// \note Macro provided for convenience; defined as a no-op if ASan is not
  67 /// enabled.
  68 ///
  69 /// \param addr Start of memory region.
  70 /// \param size Size of memory region.
  71 #define ASAN_UNPOISON_MEMORY_REGION(addr, size)                                \
  72   __asan_unpoison_memory_region((addr), (size))
  73 #else
  74 #define ASAN_POISON_MEMORY_REGION(addr, size) ((void)(addr), (void)(size))
  75 #define ASAN_UNPOISON_MEMORY_REGION(addr, size) ((void)(addr), (void)(size))
  76 #endif
  77
  78 /// Checks if an address is poisoned.
  79 ///
  80 /// Returns 1 if <c><i>addr</i></c> is poisoned (that is, 1-byte read/write
  81 /// access to this address would result in an error report from ASan).
  82 /// Otherwise returns 0.
  83 ///
  84 /// \param addr Address to check.
  85 ///
  86 /// \retval 1 Address is poisoned.
  87 /// \retval 0 Address is not poisoned.
  88 int SANITIZER_CDECL __asan_address_is_poisoned(void const volatile *addr);
  89
  90 /// Checks if a region is poisoned.
  91 ///
  92 /// If at least one byte in <c>[beg, beg+size)</c> is poisoned, returns the
  93 /// address of the first such byte. Otherwise returns 0.
  94 ///
  95 /// \param beg Start of memory region.
  96 /// \param size Start of memory region.
  97 /// \returns Address of first poisoned byte.
  98 void *SANITIZER_CDECL __asan_region_is_poisoned(void *beg, size_t size);
  99
 100 /// Describes an address (useful for calling from the debugger).
 101 ///
 102 /// Prints the description of <c><i>addr</i></c>.
 103 ///
 104 /// \param addr Address to describe.
 105 void SANITIZER_CDECL __asan_describe_address(void *addr);
 106
 107 /// Checks if an error has been or is being reported (useful for calling from
 108 /// the debugger to get information about an ASan error).
 109 ///
 110 /// Returns 1 if an error has been (or is being) reported. Otherwise returns 0.
 111 ///
 112 /// \returns 1 if an error has been (or is being) reported. Otherwise returns
 113 /// 0.
 114 int SANITIZER_CDECL __asan_report_present(void);
 115
 116 /// Gets the PC (program counter) register value of an ASan error (useful for
 117 /// calling from the debugger).
 118 ///
 119 /// Returns PC if an error has been (or is being) reported.
 120 /// Otherwise returns 0.
 121 ///
 122 /// \returns PC value.
 123 void *SANITIZER_CDECL __asan_get_report_pc(void);
 124
 125 /// Gets the BP (base pointer) register value of an ASan error (useful for
 126 /// calling from the debugger).
 127 ///
 128 /// Returns BP if an error has been (or is being) reported.
 129 /// Otherwise returns 0.
 130 ///
 131 /// \returns BP value.
 132 void *SANITIZER_CDECL __asan_get_report_bp(void);
 133
 134 /// Gets the SP (stack pointer) register value of an ASan error (useful for
 135 /// calling from the debugger).
 136 ///
 137 /// If an error has been (or is being) reported, returns SP.
 138 /// Otherwise returns 0.
 139 ///
 140 /// \returns SP value.
 141 void *SANITIZER_CDECL __asan_get_report_sp(void);
 142
 143 /// Gets the address of the report buffer of an ASan error (useful for calling
 144 /// from the debugger).
 145 ///
 146 /// Returns the address of the report buffer if an error has been (or is being)
 147 /// reported. Otherwise returns 0.
 148 ///
 149 /// \returns Address of report buffer.
 150 void *SANITIZER_CDECL __asan_get_report_address(void);
 151
 152 /// Gets access type of an ASan error (useful for calling from the debugger).
 153 ///
 154 /// Returns access type (read or write) if an error has been (or is being)
 155 /// reported. Otherwise returns 0.
 156 ///
 157 /// \returns Access type (0 = read, 1 = write).
 158 int SANITIZER_CDECL __asan_get_report_access_type(void);
 159
 160 /// Gets access size of an ASan error (useful for calling from the debugger).
 161 ///
 162 /// Returns access size if an error has been (or is being) reported. Otherwise
 163 /// returns 0.
 164 ///
 165 /// \returns Access size in bytes.
 166 size_t SANITIZER_CDECL __asan_get_report_access_size(void);
 167
 168 /// Gets the bug description of an ASan error (useful for calling from a
 169 /// debugger).
 170 ///
 171 /// \returns Returns a bug description if an error has been (or is being)
 172 /// reported - for example, "heap-use-after-free". Otherwise returns an empty
 173 /// string.
 174 const char *SANITIZER_CDECL __asan_get_report_description(void);
 175
 176 /// Gets information about a pointer (useful for calling from the debugger).
 177 ///
 178 /// Returns the category of the given pointer as a constant string.
 179 /// Possible return values are <c>global</c>, <c>stack</c>, <c>stack-fake</c>,
 180 /// <c>heap</c>, <c>heap-invalid</c>, <c>shadow-low</c>, <c>shadow-gap</c>,
 181 /// <c>shadow-high</c>, and <c>unknown</c>.
 182 ///
 183 /// If the return value is <c>global</c> or <c>stack</c>, tries to also return
 184 /// the variable name, address, and size. If the return value is <c>heap</c>,
 185 /// tries to return the chunk address and size. <c><i>name</i></c> should point
 186 /// to an allocated buffer of size <c><i>name_size</i></c>.
 187 ///
 188 /// \param addr Address to locate.
 189 /// \param name Buffer to store the variable's name.
 190 /// \param name_size Size in bytes of the variable's name buffer.
 191 /// \param[out] region_address Address of the region.
 192 /// \param[out] region_size Size of the region in bytes.
 193 ///
 194 /// \returns Returns the category of the given pointer as a constant string.
 195 const char *SANITIZER_CDECL __asan_locate_address(void *addr, char *name,
 196                                                   size_t name_size,
 197                                                   void **region_address,
 198                                                   size_t *region_size);
 199
 200 /// Gets the allocation stack trace and thread ID for a heap address (useful
 201 /// for calling from the debugger).
 202 ///
 203 /// Stores up to <c><i>size</i></c> frames in <c><i>trace</i></c>. Returns
 204 /// the number of stored frames or 0 on error.
 205 ///
 206 /// \param addr A heap address.
 207 /// \param trace A buffer to store the stack trace.
 208 /// \param size Size in bytes of the trace buffer.
 209 /// \param[out] thread_id The thread ID of the address.
 210 ///
 211 /// \returns Returns the number of stored frames or 0 on error.
 212 size_t SANITIZER_CDECL __asan_get_alloc_stack(void *addr, void **trace,
 213                                               size_t size, int *thread_id);
 214
 215 /// Gets the free stack trace and thread ID for a heap address (useful for
 216 /// calling from the debugger).
 217 ///
 218 /// Stores up to <c><i>size</i></c> frames in <c><i>trace</i></c>. Returns
 219 /// the number of stored frames or 0 on error.
 220 ///
 221 /// \param addr A heap address.
 222 /// \param trace A buffer to store the stack trace.
 223 /// \param size Size in bytes of the trace buffer.
 224 /// \param[out] thread_id The thread ID of the address.
 225 ///
 226 /// \returns Returns the number of stored frames or 0 on error.
 227 size_t SANITIZER_CDECL __asan_get_free_stack(void *addr, void **trace,
 228                                              size_t size, int *thread_id);
 229
 230 /// Gets the current shadow memory mapping (useful for calling from the
 231 /// debugger).
 232 ///
 233 /// \param[out] shadow_scale Shadow scale value.
 234 /// \param[out] shadow_offset Offset value.
 235 void SANITIZER_CDECL __asan_get_shadow_mapping(size_t *shadow_scale,
 236                                                size_t *shadow_offset);
 237
 238 /// This is an internal function that is called to report an error. However,
 239 /// it is still a part of the interface because you might want to set a
 240 /// breakpoint on this function in the debugger.
 241 ///
 242 /// \param pc <c><i>pc</i></c> value of the ASan error.
 243 /// \param bp <c><i>bp</i></c> value of the ASan error.
 244 /// \param sp <c><i>sp</i></c> value of the ASan error.
 245 /// \param addr Address of the ASan error.
 246 /// \param is_write True if the error is a write error; false otherwise.
 247 /// \param access_size Size of the memory access of the ASan error.
 248 void SANITIZER_CDECL __asan_report_error(void *pc, void *bp, void *sp,
 249                                          void *addr, int is_write,
 250                                          size_t access_size);
 251
 252 // Deprecated. Call __sanitizer_set_death_callback instead.
 253 void SANITIZER_CDECL __asan_set_death_callback(void (*callback)(void));
 254
 255 /// Sets the callback function to be called during ASan error reporting.
 256 ///
 257 /// The callback provides a string pointer to the report.
 258 ///
 259 /// \param callback User-provided function.
 260 void SANITIZER_CDECL
 261 __asan_set_error_report_callback(void (*callback)(const char *));
 262
 263 /// User-provided callback on ASan errors.
 264 ///
 265 /// You can provide a function that would be called immediately when ASan
 266 /// detects an error. This is useful in cases when ASan detects an error but
 267 /// your program crashes before the ASan report is printed.
 268 void SANITIZER_CDECL __asan_on_error(void);
 269
 270 /// Prints accumulated statistics to <c>stderr</c> (useful for calling from the
 271 /// debugger).
 272 void SANITIZER_CDECL __asan_print_accumulated_stats(void);
 273
 274 /// User-provided default option settings.
 275 ///
 276 /// You can provide your own implementation of this function to return a string
 277 /// containing ASan runtime options (for example,
 278 /// <c>verbosity=1:halt_on_error=0</c>).
 279 ///
 280 /// \returns Default options string.
 281 const char *SANITIZER_CDECL __asan_default_options(void);
 282
 283 // The following two functions facilitate garbage collection in presence of
 284 // ASan's fake stack.
 285
 286 /// Gets an opaque handler to the current thread's fake stack.
 287 ///
 288 /// Returns an opaque handler to be used by
 289 /// <c>__asan_addr_is_in_fake_stack()</c>. Returns NULL if the current thread
 290 /// does not have a fake stack.
 291 ///
 292 /// \returns An opaque handler to the fake stack or NULL.
 293 void *SANITIZER_CDECL __asan_get_current_fake_stack(void);
 294
 295 /// Checks if an address belongs to a given fake stack.
 296 ///
 297 /// If <c><i>fake_stack</i></c> is non-NULL and <c><i>addr</i></c> belongs to a
 298 /// fake frame in <c><i>fake_stack</i></c>, returns the address of the real
 299 /// stack that corresponds to the fake frame and sets <c><i>beg</i></c> and
 300 /// <c><i>end</i></c> to the boundaries of this fake frame. Otherwise returns
 301 /// NULL and does not touch <c><i>beg</i></c> and <c><i>end</i></c>.
 302 ///
 303 /// If <c><i>beg</i></c> or <c><i>end</i></c> are NULL, they are not touched.
 304 ///
 305 /// \note This function can be called from a thread other than the owner of
 306 /// <c><i>fake_stack</i></c>, but the owner thread needs to be alive.
 307 ///
 308 /// \param fake_stack An opaque handler to a fake stack.
 309 /// \param addr Address to test.
 310 /// \param[out] beg Beginning of fake frame.
 311 /// \param[out] end End of fake frame.
 312 /// \returns Stack address or NULL.
 313 void *SANITIZER_CDECL __asan_addr_is_in_fake_stack(void *fake_stack, void *addr,
 314                                                    void **beg, void **end);
 315
 316 /// Performs shadow memory cleanup of the current thread's stack before a
 317 /// function marked with the <c>[[noreturn]]</c> attribute is called.
 318 ///
 319 /// To avoid false positives on the stack, must be called before no-return
 320 /// functions like <c>_exit()</c> and <c>execl()</c>.
 321 void SANITIZER_CDECL __asan_handle_no_return(void);
 322
 323 /// Update allocation stack trace for the given allocation to the current stack
 324 /// trace. Returns 1 if successful, 0 if not.
 325 int SANITIZER_CDECL __asan_update_allocation_context(void *addr);
 326
 327 #ifdef __cplusplus
 328 } // extern "C"
 329 #endif
 330
 331 #endif // SANITIZER_ASAN_INTERFACE_H