base/sanitizer package | Odin Programming Language

The `sanitizer` package implements various procedures for interacting with sanitizers from user code. An odin project can be linked with various sanitizers to help identify various different bugs. These sanitizers are: ## Address Enabled with `-sanitize:address` when building an odin project. The address sanitizer (asan) is a runtime memory error detector used to help find common memory related bugs. Typically asan interacts with libc but Odin code can be marked up to interact with the asan runtime to extend the memory error detection outside of libc using this package. For more information about asan see: https://clang.llvm.org/docs/AddressSanitizer.html Procedures can be made exempt from asan when marked up with @(no_sanitize_address) ## Memory Enabled with `-sanitize:memory` when building an odin project. The memory sanitizer is another runtime memory error detector with the sole purpose to catch the use of uninitialized memory. This is not a very common bug in Odin as by default everything is set to zero when initialised (ZII). For more information about the memory sanitizer see: https://clang.llvm.org/docs/MemorySanitizer.html ## Thread Enabled with `-sanitize:thread` when building an odin project. The thread sanitizer is a runtime data race detector. It can be used to detect if multiple threads are concurrently writing and accessing a memory location without proper syncronisation. For more information about the thread sanitizer see: https://clang.llvm.org/docs/ThreadSanitizer.html

Collection Info

Collection: base
Path: sanitizer
Entries: 44

Source Files

Types

4

Address_Access_Type #

Address_Access_Type :: Address_Access_Type

Address_Death_Callback #

Address_Death_Callback :: Address_Death_Callback

Address_Located_Address #

Address_Located_Address :: Address_Located_Address

Address_Shadow_Mapping #

Address_Shadow_Mapping :: Address_Shadow_Mapping

Procedures

36

address_describe_address #

@(no_sanitize_address)

address_describe_address :: proc "contextless" (address: rawptr) {…}

Describes the sanitizer state for an address. This procedure prints the description out to `stdout`. When asan is not enabled this procedure does nothing.

address_get_alloc_stack_trace #

@(no_sanitize_address)

address_get_alloc_stack_trace :: proc "contextless" (addr: rawptr, data: []rawptr) -> ([]rawptr, int) {…}

Returns the allocation stack trace and thread id for a heap address. The stack trace is filled into the `data` slice. When asan is not enabled this procedure returns a zero initialised value.

address_get_current_fake_stack #

@(no_sanitize_address)

address_get_current_fake_stack :: proc "contextless" () -> rawptr {…}

Returns the address of the current fake stack used by asan. This pointer can be then used for `address_is_in_fake_stack`. When asan is not enabled this procedure returns `nil`.

address_get_free_stack_trace #

@(no_sanitize_address)

address_get_free_stack_trace :: proc "contextless" (addr: rawptr, data: []rawptr) -> ([]rawptr, int) {…}

Returns the free stack trace and thread id for a heap address. The stack trace is filled into the `data` slice. When asan is not enabled this procedure returns zero initialised values.

address_get_report_access_size #

@(no_sanitize_address)

address_get_report_access_size :: proc "contextless" () -> uint {…}

Returns the access size of an asan error. If no asan error has occurd `0` is returned. When asan is not enabled this procedure returns `0`.

address_get_report_access_type #

@(no_sanitize_address)

address_get_report_access_type :: proc "contextless" () -> Address_Access_Type {…}

Returns the address access type of an asan error. If no asan error has occurd `.none` is returned. When asan is not enabled this procedure returns `.none`.

address_get_report_address #

@(no_sanitize_address)

address_get_report_address :: proc "contextless" () -> rawptr {…}

Returns the report buffer address of an asan error. If no asan error has occurd `nil` is returned. When asan is not enabled this procedure returns `nil`.

address_get_report_bp #

@(no_sanitize_address)

address_get_report_bp :: proc "contextless" () -> rawptr {…}

Returns the base pointer register value of an asan error. If no asan error has occurd `nil` is returned. When asan is not enabled this procedure returns `nil`.

address_get_report_description #

@(no_sanitize_address)

address_get_report_description :: proc "contextless" () -> string {…}

Returns the bug description of an asan error. If no asan error has occurd an empty string is returned. When asan is not enabled this procedure returns an empty string.

address_get_report_pc #

@(no_sanitize_address)

address_get_report_pc :: proc "contextless" () -> rawptr {…}

Returns the program counter register value of an asan error. If no asan error has occurd `nil` is returned. When asan is not enabled this procedure returns `nil`.

address_get_report_sp #

@(no_sanitize_address)

address_get_report_sp :: proc "contextless" () -> rawptr {…}

Returns the stack pointer register value of an asan error. If no asan error has occurd `nil` is returned. When asan is not enabled this procedure returns `nil`.

address_get_shadow_mapping #

@(no_sanitize_address)

address_get_shadow_mapping :: proc "contextless" () -> Address_Shadow_Mapping {…}

Returns the current asan shadow memory mapping. When asan is not enabled this procedure returns a zero initialised value.

address_handle_no_return #

@(no_sanitize_address)

address_handle_no_return :: proc "contextless" () {…}

Performs shadow memory cleanup for the current thread before a procedure with no return is called i.e. a procedure such as `panic` and `os.exit`. When asan is not enabled this procedure does nothing.

address_is_in_fake_stack #

@(no_sanitize_address)

address_is_in_fake_stack :: proc "contextless" (fake_stack: rawptr, addr: rawptr) -> ([]u8, bool) {…}

Returns if an address belongs to a given fake stack and if so the region of the fake frame. When asan is not enabled this procedure returns zero initialised values.

address_is_poisoned #

@(no_sanitize_address)

address_is_poisoned :: proc "contextless" (address: rawptr) -> bool {…}

Checks if the address is poisoned. If it is poisoned this procedure returns `true`, otherwise it returns `false`. When asan is not enabled this procedure returns `false`.

address_locate_address #

@(no_sanitize_address)

address_locate_address :: proc "contextless" (addr: rawptr, data: []u8) -> Address_Located_Address {…}

Returns asan information about the address provided, writing the category into `data`. The information provided include: The category of the address, i.e. stack, global, heap, etc. The name of the variable this address belongs to The memory region of the address When asan is not enabled this procedure returns zero initialised values.

address_poison_ptr #

@(no_sanitize_address)

address_poison_ptr :: proc "contextless" (ptr: ^$T) {…}

Marks a pointer as unaddressable Code instrumented with `-sanitize:address` is forbidden from accessing any address within the region the pointer points to. This procedure is not thread-safe because no two threads can poison or unpoison memory in the same memory region region simultaneously. When asan is not enabled this procedure does nothing.

address_poison_rawptr #

@(no_sanitize_address)

address_poison_rawptr :: proc "contextless" (ptr: rawptr, len: int) {…}

Marks the region covering `[ptr, ptr+len)` as unaddressable Code instrumented with `-sanitize:address` is forbidden from accessing any address within the region. This procedure is not thread-safe because no two threads can poison or unpoison memory in the same memory region region simultaneously. When asan is not enabled this procedure does nothing.

address_poison_rawptr_uint #

@(no_sanitize_address)

address_poison_rawptr_uint :: proc "contextless" (ptr: rawptr, len: uint) {…}

Marks the region covering `[ptr, ptr+len)` as unaddressable Code instrumented with `-sanitize:address` is forbidden from accessing any address within the region. This procedure is not thread-safe because no two threads can poison or unpoison memory in the same memory region region simultaneously. When asan is not enabled this procedure does nothing.

address_poison_slice #

@(no_sanitize_address)

address_poison_slice :: proc "contextless" (region: $T/[]$E) {…}

Marks a slice as unaddressable Code instrumented with `-sanitize:address` is forbidden from accessing any address within the slice. This procedure is not thread-safe because no two threads can poison or unpoison memory in the same memory region region simultaneously. When asan is not enabled this procedure does nothing.

address_print_accumulated_stats #

@(no_sanitize_address)

address_print_accumulated_stats :: proc "contextless" () {…}

Prints asan statistics to `stderr` When asan is not enabled this procedure does nothing.

address_region_is_poisoned_ptr #

@(no_sanitize_address)

address_region_is_poisoned_ptr :: proc "contextless" (ptr: ^$T) -> rawptr {…}

Checks if the memory region pointed to by the pointer is poisoned. If it is poisoned this procedure returns the address which would result in an asan error. When asan is not enabled this procedure returns `nil`.

address_region_is_poisoned_rawptr #

@(no_sanitize_address)

address_region_is_poisoned_rawptr :: proc "contextless" (region: rawptr, len: int) -> rawptr {…}

Checks if the memory region covered by `[ptr, ptr+len)` is poisoned. If it is poisoned this procedure returns the address which would result in an asan error. When asan is not enabled this procedure returns `nil`.

address_region_is_poisoned_rawptr_uint #

@(no_sanitize_address)

address_region_is_poisoned_rawptr_uint :: proc "contextless" (region: rawptr, len: uint) -> rawptr {…}

Checks if the memory region covered by `[ptr, ptr+len)` is poisoned. If it is poisoned this procedure returns the address which would result in an asan error. When asan is not enabled this procedure returns `nil`.

address_region_is_poisoned_slice #

@(no_sanitize_address)

address_region_is_poisoned_slice :: proc "contextless" (region: $T/[]$E) -> rawptr {…}

Checks if the memory region covered by the slice is poisoned. If it is poisoned this procedure returns the address which would result in an asan error. When asan is not enabled this procedure returns `nil`.

address_report_present #

@(no_sanitize_address)

address_report_present :: proc "contextless" () -> bool {…}

Returns `true` if an asan error has occured, otherwise it returns `false`. When asan is not enabled this procedure returns `false`.

address_set_death_callback #

@(no_sanitize_address)

address_set_death_callback :: proc "contextless" (callback: Address_Death_Callback) {…}

Registers a callback to be run when asan detects a memory error right before terminating the process. This can be used for logging and/or debugging purposes. When asan is not enabled this procedure does nothing.

address_unpoison_ptr #

@(no_sanitize_address)

address_unpoison_ptr :: proc "contextless" (ptr: ^$T) {…}

Marks a pointer as addressable Code instrumented with `-sanitize:address` is allowed to access any address within the region the pointer points to again. This procedure is not thread-safe because no two threads can poison or unpoison memory in the same memory region region simultaneously. When asan is not enabled this procedure does nothing.

address_unpoison_rawptr #

@(no_sanitize_address)

address_unpoison_rawptr :: proc "contextless" (ptr: rawptr, len: int) {…}

Marks the region covering `[ptr, ptr+len)` as addressable Code instrumented with `-sanitize:address` is allowed to access any address within the region again. This procedure is not thread-safe because no two threads can poison or unpoison memory in the same memory region region simultaneously. When asan is not enabled this procedure does nothing.

address_unpoison_rawptr_uint #

@(no_sanitize_address)

address_unpoison_rawptr_uint :: proc "contextless" (ptr: rawptr, len: uint) {…}

Marks the region covering `[ptr, ptr+len)` as addressable Code instrumented with `-sanitize:address` is allowed to access any address within the region again. This procedure is not thread-safe because no two threads can poison or unpoison memory in the same memory region region simultaneously. When asan is not enabled this procedure does nothing.

address_unpoison_slice #

@(no_sanitize_address)

address_unpoison_slice :: proc "contextless" (region: $T/[]$E) {…}

Marks a slice as addressable Code instrumented with `-sanitize:address` is allowed to access any address within the slice again. This procedure is not thread-safe because no two threads can poison or unpoison memory in the same memory region region simultaneously. When asan is not enabled this procedure does nothing.

address_update_allocation_context #

@(no_sanitize_address)

address_update_allocation_context :: proc "contextless" (addr: rawptr) -> bool {…}

Updates the allocation stack trace for the given address. Returns `true` if successful, otherwise it returns `false`. When asan is not enabled this procedure returns `false`.

memory_unpoison_ptr #

memory_unpoison_ptr :: proc "contextless" (ptr: ^$T) {…}

Marks a pointer as fully initialized. Code instrumented with `-sanitize:memory` will be permitted to access memory within the region the pointer points to as if it had already been initialized. When msan is not enabled this procedure does nothing.

memory_unpoison_rawptr #

memory_unpoison_rawptr :: proc "contextless" (ptr: rawptr, len: int) {…}

Marks the region covering `[ptr, ptr+len)` as fully initialized. Code instrumented with `-sanitize:memory` will be permitted to access memory within this range as if it had already been initialized. When msan is not enabled this procedure does nothing.

memory_unpoison_rawptr_uint #

memory_unpoison_rawptr_uint :: proc "contextless" (ptr: rawptr, len: uint) {…}

Marks the region covering `[ptr, ptr+len)` as fully initialized. Code instrumented with `-sanitize:memory` will be permitted to access memory within this range as if it had already been initialized. When msan is not enabled this procedure does nothing.

memory_unpoison_slice #

memory_unpoison_slice :: proc "contextless" (region: $T/[]$E) {…}

Marks a slice as fully initialized. Code instrumented with `-sanitize:memory` will be permitted to access any address within the slice as if it had already been initialized. When msan is not enabled this procedure does nothing.

Procedure Groups

4

address_poison #

address_poison :: proc{
	address_poison_slice,
	address_poison_ptr,
	address_poison_rawptr,
	address_poison_rawptr_uint,
}

address_region_is_poisoned #

address_region_is_poisoned :: proc{
	address_region_is_poisoned_slice,
	address_region_is_poisoned_ptr,
	address_region_is_poisoned_rawptr,
	address_region_is_poisoned_rawptr_uint,
}

address_unpoison #

address_unpoison :: proc{
	address_unpoison_slice,
	address_unpoison_ptr,
	address_unpoison_rawptr,
	address_unpoison_rawptr_uint,
}

memory_unpoison #

memory_unpoison :: proc{
	memory_unpoison_slice,
	memory_unpoison_ptr,
	memory_unpoison_rawptr,
	memory_unpoison_rawptr_uint,
}