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