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 __asan_poison_memory_region(void const volatile *addr, size_t size); 35 36 /// Marks a memory region (<c>[addr, addr+size)</c>) as addressable. 37 /// 38 /// This memory must be previously allocated by your program. Accessing 39 /// addresses in this region is allowed until this region is poisoned again. 40 /// This function could unpoison a super-region of <c>[addr, addr+size)</c> due 41 /// to ASan alignment restrictions. 42 /// 43 /// \note This function is not thread-safe because no two threads can 44 /// poison or unpoison memory in the same memory region simultaneously. 45 /// 46 /// \param addr Start of memory region. 47 /// \param size Size of memory region. 48 void __asan_unpoison_memory_region(void const volatile *addr, size_t size); 49 50 // Macros provided for convenience. 51 #if __has_feature(address_sanitizer) || defined(__SANITIZE_ADDRESS__) 52 /// Marks a memory region as unaddressable. 53 /// 54 /// \note Macro provided for convenience; defined as a no-op if ASan is not 55 /// enabled. 56 /// 57 /// \param addr Start of memory region. 58 /// \param size Size of memory region. 59 #define ASAN_POISON_MEMORY_REGION(addr, size) \ 60 __asan_poison_memory_region((addr), (size)) 61 62 /// Marks a memory region as addressable. 63 /// 64 /// \note Macro provided for convenience; defined as a no-op if ASan is not 65 /// enabled. 66 /// 67 /// \param addr Start of memory region. 68 /// \param size Size of memory region. 69 #define ASAN_UNPOISON_MEMORY_REGION(addr, size) \ 70 __asan_unpoison_memory_region((addr), (size)) 71 #else 72 #define ASAN_POISON_MEMORY_REGION(addr, size) \ 73 ((void)(addr), (void)(size)) 74 #define ASAN_UNPOISON_MEMORY_REGION(addr, size) \ 75 ((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 __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 *__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 __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 __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 *__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 *__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 *__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 *__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 __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 __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 *__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 *__asan_locate_address(void *addr, char *name, size_t name_size, 196 void **region_address, size_t *region_size); 197 198 /// Gets the allocation stack trace and thread ID for a heap address (useful 199 /// for calling from the debugger). 200 /// 201 /// Stores up to <c><i>size</i></c> frames in <c><i>trace</i></c>. Returns 202 /// the number of stored frames or 0 on error. 203 /// 204 /// \param addr A heap address. 205 /// \param trace A buffer to store the stack trace. 206 /// \param size Size in bytes of the trace buffer. 207 /// \param[out] thread_id The thread ID of the address. 208 /// 209 /// \returns Returns the number of stored frames or 0 on error. 210 size_t __asan_get_alloc_stack(void *addr, void **trace, size_t size, 211 int *thread_id); 212 213 /// Gets the free stack trace and thread ID for a heap address (useful for 214 /// calling from the debugger). 215 /// 216 /// Stores up to <c><i>size</i></c> frames in <c><i>trace</i></c>. Returns 217 /// the number of stored frames or 0 on error. 218 /// 219 /// \param addr A heap address. 220 /// \param trace A buffer to store the stack trace. 221 /// \param size Size in bytes of the trace buffer. 222 /// \param[out] thread_id The thread ID of the address. 223 /// 224 /// \returns Returns the number of stored frames or 0 on error. 225 size_t __asan_get_free_stack(void *addr, void **trace, size_t size, 226 int *thread_id); 227 228 /// Gets the current shadow memory mapping (useful for calling from the 229 /// debugger). 230 /// 231 /// \param[out] shadow_scale Shadow scale value. 232 /// \param[out] shadow_offset Offset value. 233 void __asan_get_shadow_mapping(size_t *shadow_scale, size_t *shadow_offset); 234 235 /// This is an internal function that is called to report an error. However, 236 /// it is still a part of the interface because you might want to set a 237 /// breakpoint on this function in the debugger. 238 /// 239 /// \param pc <c><i>pc</i></c> value of the ASan error. 240 /// \param bp <c><i>bp</i></c> value of the ASan error. 241 /// \param sp <c><i>sp</i></c> value of the ASan error. 242 /// \param addr Address of the ASan error. 243 /// \param is_write True if the error is a write error; false otherwise. 244 /// \param access_size Size of the memory access of the ASan error. 245 void __asan_report_error(void *pc, void *bp, void *sp, 246 void *addr, int is_write, size_t access_size); 247 248 // Deprecated. Call __sanitizer_set_death_callback instead. 249 void __asan_set_death_callback(void (*callback)(void)); 250 251 /// Sets the callback function to be called during ASan error reporting. 252 /// 253 /// The callback provides a string pointer to the report. 254 /// 255 /// \param callback User-provided function. 256 void __asan_set_error_report_callback(void (*callback)(const char *)); 257 258 /// User-provided callback on ASan errors. 259 /// 260 /// You can provide a function that would be called immediately when ASan 261 /// detects an error. This is useful in cases when ASan detects an error but 262 /// your program crashes before the ASan report is printed. 263 void __asan_on_error(void); 264 265 /// Prints accumulated statistics to <c>stderr</c> (useful for calling from the 266 /// debugger). 267 void __asan_print_accumulated_stats(void); 268 269 /// User-provided default option settings. 270 /// 271 /// You can provide your own implementation of this function to return a string 272 /// containing ASan runtime options (for example, 273 /// <c>verbosity=1:halt_on_error=0</c>). 274 /// 275 /// \returns Default options string. 276 const char* __asan_default_options(void); 277 278 // The following two functions facilitate garbage collection in presence of 279 // ASan's fake stack. 280 281 /// Gets an opaque handler to the current thread's fake stack. 282 /// 283 /// Returns an opaque handler to be used by 284 /// <c>__asan_addr_is_in_fake_stack()</c>. Returns NULL if the current thread 285 /// does not have a fake stack. 286 /// 287 /// \returns An opaque handler to the fake stack or NULL. 288 void *__asan_get_current_fake_stack(void); 289 290 /// Checks if an address belongs to a given fake stack. 291 /// 292 /// If <c><i>fake_stack</i></c> is non-NULL and <c><i>addr</i></c> belongs to a 293 /// fake frame in <c><i>fake_stack</i></c>, returns the address of the real 294 /// stack that corresponds to the fake frame and sets <c><i>beg</i></c> and 295 /// <c><i>end</i></c> to the boundaries of this fake frame. Otherwise returns 296 /// NULL and does not touch <c><i>beg</i></c> and <c><i>end</i></c>. 297 /// 298 /// If <c><i>beg</i></c> or <c><i>end</i></c> are NULL, they are not touched. 299 /// 300 /// \note This function can be called from a thread other than the owner of 301 /// <c><i>fake_stack</i></c>, but the owner thread needs to be alive. 302 /// 303 /// \param fake_stack An opaque handler to a fake stack. 304 /// \param addr Address to test. 305 /// \param[out] beg Beginning of fake frame. 306 /// \param[out] end End of fake frame. 307 /// \returns Stack address or NULL. 308 void *__asan_addr_is_in_fake_stack(void *fake_stack, void *addr, void **beg, 309 void **end); 310 311 /// Performs shadow memory cleanup of the current thread's stack before a 312 /// function marked with the <c>[[noreturn]]</c> attribute is called. 313 /// 314 /// To avoid false positives on the stack, must be called before no-return 315 /// functions like <c>_exit()</c> and <c>execl()</c>. 316 void __asan_handle_no_return(void); 317 318 /// Update allocation stack trace for the given allocation to the current stack 319 /// trace. Returns 1 if successful, 0 if not. 320 int __asan_update_allocation_context(void* addr); 321 322 #ifdef __cplusplus 323 } // extern "C" 324 #endif 325 326 #endif // SANITIZER_ASAN_INTERFACE_H 327