asan_interface.h File Reference

#include <sanitizer/common_interface_defs.h>

Include dependency graph for asan_interface.h:

Go to the source code of this file.

Macros
#define	ASAN_POISON_MEMORY_REGION(addr, size)    ((void)(addr), (void)(size))
#define	ASAN_UNPOISON_MEMORY_REGION(addr, size)    ((void)(addr), (void)(size))

Functions
void	__asan_poison_memory_region (void const volatile *addr, size_t size)
	Marks a memory region ([addr, addr+size)) as unaddressable. More...
void	__asan_unpoison_memory_region (void const volatile *addr, size_t size)
	Marks a memory region ([addr, addr+size)) as addressable. More...
int	__asan_address_is_poisoned (void const volatile *addr)
	Checks if an address is poisoned. More...
void *	__asan_region_is_poisoned (void *beg, size_t size)
	Checks if a region is poisoned. More...
void	__asan_describe_address (void *addr)
	Describes an address (useful for calling from the debugger). More...
int	__asan_report_present (void)
	Checks if an error has been or is being reported (useful for calling from the debugger to get information about an ASan error). More...
void *	__asan_get_report_pc (void)
	Gets the PC (program counter) register value of an ASan error (useful for calling from the debugger). More...
void *	__asan_get_report_bp (void)
	Gets the BP (base pointer) register value of an ASan error (useful for calling from the debugger). More...
void *	__asan_get_report_sp (void)
	Gets the SP (stack pointer) register value of an ASan error (useful for calling from the debugger). More...
void *	__asan_get_report_address (void)
	Gets the address of the report buffer of an ASan error (useful for calling from the debugger). More...
int	__asan_get_report_access_type (void)
	Gets access type of an ASan error (useful for calling from the debugger). More...
size_t	__asan_get_report_access_size (void)
	Gets access size of an ASan error (useful for calling from the debugger). More...
const char *	__asan_get_report_description (void)
	Gets the bug description of an ASan error (useful for calling from a debugger). More...
const char *	__asan_locate_address (void *addr, char *name, size_t name_size, void **region_address, size_t *region_size)
	Gets information about a pointer (useful for calling from the debugger). More...
size_t	__asan_get_alloc_stack (void *addr, void **trace, size_t size, int *thread_id)
	Gets the allocation stack trace and thread ID for a heap address (useful for calling from the debugger). More...
size_t	__asan_get_free_stack (void *addr, void **trace, size_t size, int *thread_id)
	Gets the free stack trace and thread ID for a heap address (useful for calling from the debugger). More...
void	__asan_get_shadow_mapping (size_t *shadow_scale, size_t *shadow_offset)
	Gets the current shadow memory mapping (useful for calling from the debugger). More...
void	__asan_report_error (void *pc, void *bp, void *sp, void *addr, int is_write, size_t access_size)
	This is an internal function that is called to report an error. More...
void	__asan_set_death_callback (void(*callback)(void))
void	__asan_set_error_report_callback (void(*callback)(const char *))
	Sets the callback function to be called during ASan error reporting. More...
void	__asan_on_error (void)
	User-provided callback on ASan errors. More...
void	__asan_print_accumulated_stats (void)
	Prints accumulated statistics to stderr (useful for calling from the debugger). More...
const char *	__asan_default_options (void)
	User-provided default option settings. More...
void *	__asan_get_current_fake_stack (void)
	Gets an opaque handler to the current thread's fake stack. More...
void *	__asan_addr_is_in_fake_stack (void *fake_stack, void *addr, void **beg, void **end)
	Checks if an address belongs to a given fake stack. More...
void	__asan_handle_no_return (void)
	Performs shadow memory cleanup of the current thread's stack before a function marked with the [[noreturn]] attribute is called. More...
int	__asan_update_allocation_context (void *addr)
	Update allocation stack trace for the given allocation to the current stack trace. More...

Macro Definition Documentation

ASAN_POISON_MEMORY_REGION

#define ASAN_POISON_MEMORY_REGION	(		addr,
			size
	)		((void)(addr), (void)(size))

Definition at line 72 of file asan_interface.h.

ASAN_UNPOISON_MEMORY_REGION

#define ASAN_UNPOISON_MEMORY_REGION	(		addr,
			size
	)		((void)(addr), (void)(size))

Definition at line 74 of file asan_interface.h.

Function Documentation

__asan_addr_is_in_fake_stack()

void* __asan_addr_is_in_fake_stack	(	void *	fake_stack,
		void *	addr,
		void **	beg,
		void **	end
	)

Checks if an address belongs to a given fake stack.

If fake_stack is non-NULL and addr belongs to a fake frame in fake_stack, returns the address of the real stack that corresponds to the fake frame and sets beg and end to the boundaries of this fake frame. Otherwise returns NULL and does not touch beg and end.

If beg or end are NULL, they are not touched.

Note

This function can be called from a thread other than the owner of fake_stack, but the owner thread needs to be alive.

Parameters

fake_stack	An opaque handler to a fake stack.
addr	Address to test.
beg	[out] Beginning of fake frame.
end	[out] End of fake frame.

Returns

Stack address or NULL.

__asan_address_is_poisoned()

int __asan_address_is_poisoned

(

void const volatile *

addr

)

Checks if an address is poisoned.

Returns 1 if addr is poisoned (that is, 1-byte read/write access to this address would result in an error report from ASan). Otherwise returns 0.

Parameters

addr	Address to check.

Return values

1	Address is poisoned.
0	Address is not poisoned.

__asan_default_options()

const char* __asan_default_options

(

void

)

User-provided default option settings.

You can provide your own implementation of this function to return a string containing ASan runtime options (for example, verbosity=1:halt_on_error=0).

Returns

Default options string.

__asan_describe_address()

void __asan_describe_address

(

void *

addr

)

Describes an address (useful for calling from the debugger).

Prints the description of addr.

Parameters

addr	Address to describe.

__asan_get_alloc_stack()

size_t __asan_get_alloc_stack	(	void *	addr,
		void **	trace,
		size_t	size,
		int *	thread_id
	)

Gets the allocation stack trace and thread ID for a heap address (useful for calling from the debugger).

Stores up to size frames in trace. Returns the number of stored frames or 0 on error.

Parameters

addr	A heap address.
trace	A buffer to store the stack trace.
size	Size in bytes of the trace buffer.
thread_id	[out] The thread ID of the address.

Returns

Returns the number of stored frames or 0 on error.

__asan_get_current_fake_stack()

void* __asan_get_current_fake_stack

(

void

)

Gets an opaque handler to the current thread's fake stack.

Returns an opaque handler to be used by __asan_addr_is_in_fake_stack(). Returns NULL if the current thread does not have a fake stack.

Returns

An opaque handler to the fake stack or NULL.

__asan_get_free_stack()

size_t __asan_get_free_stack	(	void *	addr,
		void **	trace,
		size_t	size,
		int *	thread_id
	)

Gets the free stack trace and thread ID for a heap address (useful for calling from the debugger).

Stores up to size frames in trace. Returns the number of stored frames or 0 on error.

Parameters

addr	A heap address.
trace	A buffer to store the stack trace.
size	Size in bytes of the trace buffer.
thread_id	[out] The thread ID of the address.

Returns

Returns the number of stored frames or 0 on error.

__asan_get_report_access_size()

size_t __asan_get_report_access_size

(

void

)

Gets access size of an ASan error (useful for calling from the debugger).

Returns access size if an error has been (or is being) reported. Otherwise returns 0.

Returns

Access size in bytes.

__asan_get_report_access_type()

int __asan_get_report_access_type

(

void

)

Gets access type of an ASan error (useful for calling from the debugger).

Returns access type (read or write) if an error has been (or is being) reported. Otherwise returns 0.

Returns

Access type (0 = read, 1 = write).

__asan_get_report_address()

void* __asan_get_report_address

(

void

)

Gets the address of the report buffer of an ASan error (useful for calling from the debugger).

Returns the address of the report buffer if an error has been (or is being) reported. Otherwise returns 0.

Returns

Address of report buffer.

__asan_get_report_bp()

void* __asan_get_report_bp

(

void

)

Gets the BP (base pointer) register value of an ASan error (useful for calling from the debugger).

Returns BP if an error has been (or is being) reported. Otherwise returns 0.

Returns

BP value.

__asan_get_report_description()

const char* __asan_get_report_description

(

void

)

Gets the bug description of an ASan error (useful for calling from a debugger).

Returns

Returns a bug description if an error has been (or is being) reported - for example, "heap-use-after-free". Otherwise returns an empty string.

__asan_get_report_pc()

void* __asan_get_report_pc

(

void

)

Gets the PC (program counter) register value of an ASan error (useful for calling from the debugger).

Returns PC if an error has been (or is being) reported. Otherwise returns 0.

Returns

PC value.

__asan_get_report_sp()

void* __asan_get_report_sp

(

void

)

Gets the SP (stack pointer) register value of an ASan error (useful for calling from the debugger).

If an error has been (or is being) reported, returns SP. Otherwise returns 0.

Returns

SP value.

__asan_get_shadow_mapping()

void __asan_get_shadow_mapping	(	size_t *	shadow_scale,
		size_t *	shadow_offset
	)

Gets the current shadow memory mapping (useful for calling from the debugger).

Parameters

shadow_scale	[out] Shadow scale value.
shadow_offset	[out] Offset value.

__asan_handle_no_return()

void __asan_handle_no_return

(

void

)

Performs shadow memory cleanup of the current thread's stack before a function marked with the [[noreturn]] attribute is called.

To avoid false positives on the stack, must be called before no-return functions like _exit() and execl().

__asan_locate_address()

const char* __asan_locate_address	(	void *	addr,
		char *	name,
		size_t	name_size,
		void **	region_address,
		size_t *	region_size
	)

Gets information about a pointer (useful for calling from the debugger).

Returns the category of the given pointer as a constant string. Possible return values are global, stack, stack-fake, heap, heap-invalid, shadow-low, shadow-gap, shadow-high, and unknown.

If the return value is global or stack, tries to also return the variable name, address, and size. If the return value is heap, tries to return the chunk address and size. name should point to an allocated buffer of size name_size.

Parameters

addr	Address to locate.
name	Buffer to store the variable's name.
name_size	Size in bytes of the variable's name buffer.
region_address	[out] Address of the region.
region_size	[out] Size of the region in bytes.

Returns

Returns the category of the given pointer as a constant string.

__asan_on_error()

void __asan_on_error

(

void

)

User-provided callback on ASan errors.

You can provide a function that would be called immediately when ASan detects an error. This is useful in cases when ASan detects an error but your program crashes before the ASan report is printed.

__asan_poison_memory_region()

void __asan_poison_memory_region	(	void const volatile *	addr,
		size_t	size
	)

Marks a memory region ([addr, addr+size)) as unaddressable.

This memory must be previously allocated by your program. Instrumented code is forbidden from accessing addresses in this region until it is unpoisoned. This function is not guaranteed to poison the entire region - it could poison only a subregion of [addr, addr+size) due to ASan alignment restrictions.

Note

This function is not thread-safe because no two threads can poison or unpoison memory in the same memory region simultaneously.

Parameters

addr	Start of memory region.
size	Size of memory region.

__asan_print_accumulated_stats()

void __asan_print_accumulated_stats

(

void

)

Prints accumulated statistics to stderr (useful for calling from the debugger).

__asan_region_is_poisoned()

void* __asan_region_is_poisoned	(	void *	beg,
		size_t	size
	)

Checks if a region is poisoned.

If at least one byte in [beg, beg+size) is poisoned, returns the address of the first such byte. Otherwise returns 0.

Parameters

beg	Start of memory region.
size	Start of memory region.

Returns

Address of first poisoned byte.

__asan_report_error()

void __asan_report_error	(	void *	pc,
		void *	bp,
		void *	sp,
		void *	addr,
		int	is_write,
		size_t	access_size
	)

This is an internal function that is called to report an error.

However, it is still a part of the interface because you might want to set a breakpoint on this function in the debugger.

Parameters

pc	pc value of the ASan error.
bp	bp value of the ASan error.
sp	sp value of the ASan error.
addr	Address of the ASan error.
is_write	True if the error is a write error; false otherwise.
access_size	Size of the memory access of the ASan error.

__asan_report_present()

int __asan_report_present

(

void

)

Checks if an error has been or is being reported (useful for calling from the debugger to get information about an ASan error).

Returns 1 if an error has been (or is being) reported. Otherwise returns 0.

Returns

1 if an error has been (or is being) reported. Otherwise returns 0.

__asan_set_death_callback()

void __asan_set_death_callback

(

void(*)(void)

callback

)

__asan_set_error_report_callback()

void __asan_set_error_report_callback

(

void(*)(const char *)

callback

)

Sets the callback function to be called during ASan error reporting.

The callback provides a string pointer to the report.

Parameters

callback

User-provided function.

__asan_unpoison_memory_region()

void __asan_unpoison_memory_region	(	void const volatile *	addr,
		size_t	size
	)

Marks a memory region ([addr, addr+size)) as addressable.

This memory must be previously allocated by your program. Accessing addresses in this region is allowed until this region is poisoned again. This function could unpoison a super-region of [addr, addr+size) due to ASan alignment restrictions.

Note

This function is not thread-safe because no two threads can poison or unpoison memory in the same memory region simultaneously.

Parameters

addr	Start of memory region.
size	Size of memory region.

__asan_update_allocation_context()

int __asan_update_allocation_context

(

void *

addr

)

Update allocation stack trace for the given allocation to the current stack trace.

Returns 1 if successfull, 0 if not.