341 lines · c
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-exception6//7//===----------------------------------------------------------------------===//8//9// This file is a part of AddressSanitizer (ASan).10//11// Public interface header.12//===----------------------------------------------------------------------===//13#ifndef SANITIZER_ASAN_INTERFACE_H14#define SANITIZER_ASAN_INTERFACE_H15 16#include <sanitizer/common_interface_defs.h>17 18#ifdef __cplusplus19extern "C" {20#endif21/// Marks a memory region (<c>[addr, addr+size)</c>) as unaddressable.22///23/// This memory must be previously allocated by your program. Instrumented24/// code is forbidden from accessing addresses in this region until it is25/// 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 ASan27/// alignment restrictions.28///29/// \note This function is not thread-safe because no two threads can poison or30/// unpoison memory in the same memory region simultaneously.31///32/// \param addr Start of memory region.33/// \param size Size of memory region.34void 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. Accessing40/// 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> due42/// to ASan alignment restrictions.43///44/// \note This function is not thread-safe because no two threads can45/// 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.49void SANITIZER_CDECL __asan_unpoison_memory_region(void const volatile *addr,50 size_t size);51 52// Macros provided for convenience.53#ifdef __has_feature54#if __has_feature(address_sanitizer)55#define ASAN_DEFINE_REGION_MACROS56#endif57#elif defined(__SANITIZE_ADDRESS__)58#define ASAN_DEFINE_REGION_MACROS59#endif60 61#ifdef ASAN_DEFINE_REGION_MACROS62/// Marks a memory region as unaddressable.63///64/// \note Macro provided for convenience; defined as a no-op if ASan is not65/// 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 not75/// 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#else82#define ASAN_POISON_MEMORY_REGION(addr, size) ((void)(addr), (void)(size))83#define ASAN_UNPOISON_MEMORY_REGION(addr, size) ((void)(addr), (void)(size))84#endif85#undef ASAN_DEFINE_REGION_MACROS86 87/// Checks if an address is poisoned.88///89/// Returns 1 if <c><i>addr</i></c> is poisoned (that is, 1-byte read/write90/// 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.97int 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 the102/// 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.107void *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.114void SANITIZER_CDECL __asan_describe_address(void *addr);115 116/// Checks if an error has been or is being reported (useful for calling from117/// 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 returns122/// 0.123int SANITIZER_CDECL __asan_report_present(void);124 125/// Gets the PC (program counter) register value of an ASan error (useful for126/// 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.132void *SANITIZER_CDECL __asan_get_report_pc(void);133 134/// Gets the BP (base pointer) register value of an ASan error (useful for135/// 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.141void *SANITIZER_CDECL __asan_get_report_bp(void);142 143/// Gets the SP (stack pointer) register value of an ASan error (useful for144/// 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.150void *SANITIZER_CDECL __asan_get_report_sp(void);151 152/// Gets the address of the report buffer of an ASan error (useful for calling153/// 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.159void *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).167int 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. Otherwise172/// returns 0.173///174/// \returns Access size in bytes.175size_t SANITIZER_CDECL __asan_get_report_access_size(void);176 177/// Gets the bug description of an ASan error (useful for calling from a178/// 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 empty182/// string.183const 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 return193/// 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 point195/// 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.204const 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 (useful210/// for calling from the debugger).211///212/// Stores up to <c><i>size</i></c> frames in <c><i>trace</i></c>. Returns213/// 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.221size_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 for225/// calling from the debugger).226///227/// Stores up to <c><i>size</i></c> frames in <c><i>trace</i></c>. Returns228/// 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.236size_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 the240/// debugger).241///242/// \param[out] shadow_scale Shadow scale value.243/// \param[out] shadow_offset Offset value.244void 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 a249/// 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.257void 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.262void 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.269void SANITIZER_CDECL270__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 ASan275/// detects an error. This is useful in cases when ASan detects an error but276/// your program crashes before the ASan report is printed.277void SANITIZER_CDECL __asan_on_error(void);278 279/// Prints accumulated statistics to <c>stderr</c> (useful for calling from the280/// debugger).281void 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 string286/// containing ASan runtime options (for example,287/// <c>verbosity=1:halt_on_error=0</c>).288///289/// \returns Default options string.290const char *SANITIZER_CDECL __asan_default_options(void);291 292// The following two functions facilitate garbage collection in presence of293// 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 by298/// <c>__asan_addr_is_in_fake_stack()</c>. Returns NULL if the current thread299/// does not have a fake stack.300///301/// \returns An opaque handler to the fake stack or NULL.302void *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 a307/// fake frame in <c><i>fake_stack</i></c>, returns the address of the real308/// stack that corresponds to the fake frame and sets <c><i>beg</i></c> and309/// <c><i>end</i></c> to the boundaries of this fake frame. Otherwise returns310/// 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 of315/// <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.322void *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 a326/// function marked with the <c>[[noreturn]]</c> attribute is called.327///328/// To avoid false positives on the stack, must be called before no-return329/// functions like <c>_exit()</c> and <c>execl()</c>.330void SANITIZER_CDECL __asan_handle_no_return(void);331 332/// Update allocation stack trace for the given allocation to the current stack333/// trace. Returns 1 if successful, 0 if not.334int SANITIZER_CDECL __asan_update_allocation_context(void *addr);335 336#ifdef __cplusplus337} // extern "C"338#endif339 340#endif // SANITIZER_ASAN_INTERFACE_H341