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 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.
49void 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.
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 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.
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 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.
123int 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.
132void *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.
141void *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.
150void *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.
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. Otherwise
172/// 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 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.
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 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.
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 (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.
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 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.
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 the
240/// 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 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.
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_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.
277void SANITIZER_CDECL __asan_on_error(void);
278
279/// Prints accumulated statistics to <c>stderr</c> (useful for calling from the
280/// 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 string
286/// 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 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.
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 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.
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 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>.
330void 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.
334int 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

source code of compiler-rt/include/sanitizer/asan_interface.h