asan_interface.h revision 353358
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 19extern "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. 34void __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. 48void __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. 88int __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. 98void *__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. 105void __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. 114int __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. 123void *__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. 132void *__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. 141void *__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. 150void *__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). 158int __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. 166size_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. 174const 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 region_address [out] Address of the region. 192/// \param region_size [out] Size of the region in bytes. 193/// 194/// \returns Returns the category of the given pointer as a constant string. 195const 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 thread_id [out] The thread ID of the address. 208/// 209/// \returns Returns the number of stored frames or 0 on error. 210size_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 thread_id [out] The thread ID of the address. 223/// 224/// \returns Returns the number of stored frames or 0 on error. 225size_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 shadow_scale [out] Shadow scale value. 232/// \param shadow_offset [out] Offset value. 233void __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. 245void __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. 249void __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. 256void __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. 263void __asan_on_error(void); 264 265/// Prints accumulated statistics to <c>stderr</c> (useful for calling from the 266/// debugger). 267void __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. 276const 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. 288void *__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 beg [out] Beginning of fake frame. 306/// \param end [out] End of fake frame. 307/// \returns Stack address or NULL. 308void *__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>. 316void __asan_handle_no_return(void); 317 318#ifdef __cplusplus 319} // extern "C" 320#endif 321 322#endif // SANITIZER_ASAN_INTERFACE_H 323