1 //===-- sanitizer/asan_interface.h ------------------------------*- C++ -*-===//
3 // This file is distributed under the University of Illinois Open Source
4 // License. See LICENSE.TXT for details.
6 //===----------------------------------------------------------------------===//
8 // This file is a part of AddressSanitizer, an address sanity checker.
10 // This header can be included by the instrumented program to fetch
11 // data (mostly allocator statistics) from ASan runtime library.
12 //===----------------------------------------------------------------------===//
13 #ifndef SANITIZER_ASAN_INTERFACE_H
14 #define SANITIZER_ASAN_INTERFACE_H
16 #include <sanitizer/common_interface_defs.h>
18 // ----------- ATTENTION -------------
19 // This header should NOT include any other headers from ASan runtime.
20 // All functions in this header are extern "C" and start with __asan_.
22 using __sanitizer::uptr
;
25 // This function should be called at the very beginning of the process,
26 // before any instrumented code is executed and before any call to malloc.
27 void __asan_init() SANITIZER_INTERFACE_ATTRIBUTE
;
29 // This function should be called by the instrumented code.
30 // 'addr' is the address of a global variable called 'name' of 'size' bytes.
31 void __asan_register_global(uptr addr
, uptr size
, const char *name
)
32 SANITIZER_INTERFACE_ATTRIBUTE
;
34 // This structure describes an instrumented global variable.
35 struct __asan_global
{
36 uptr beg
; // The address of the global.
37 uptr size
; // The original size of the global.
38 uptr size_with_redzone
; // The size with the redzone.
39 const char *name
; // Name as a C string.
40 uptr has_dynamic_init
; // Non-zero if the global has dynamic initializer.
43 // These two functions should be called by the instrumented code.
44 // 'globals' is an array of structures describing 'n' globals.
45 void __asan_register_globals(__asan_global
*globals
, uptr n
)
46 SANITIZER_INTERFACE_ATTRIBUTE
;
47 void __asan_unregister_globals(__asan_global
*globals
, uptr n
)
48 SANITIZER_INTERFACE_ATTRIBUTE
;
50 // These two functions should be called before and after dynamic initializers
51 // run, respectively. They should be called with parameters describing all
52 // dynamically initialized globals defined in the calling TU.
53 void __asan_before_dynamic_init(uptr first_addr
, uptr last_addr
)
54 SANITIZER_INTERFACE_ATTRIBUTE
;
55 void __asan_after_dynamic_init()
56 SANITIZER_INTERFACE_ATTRIBUTE
;
58 // These two functions are used by the instrumented code in the
59 // use-after-return mode. __asan_stack_malloc allocates size bytes of
60 // fake stack and __asan_stack_free poisons it. real_stack is a pointer to
61 // the real stack region.
62 uptr
__asan_stack_malloc(uptr size
, uptr real_stack
)
63 SANITIZER_INTERFACE_ATTRIBUTE
;
64 void __asan_stack_free(uptr ptr
, uptr size
, uptr real_stack
)
65 SANITIZER_INTERFACE_ATTRIBUTE
;
67 // Marks memory region [addr, addr+size) as unaddressable.
68 // This memory must be previously allocated by the user program. Accessing
69 // addresses in this region from instrumented code is forbidden until
70 // this region is unpoisoned. This function is not guaranteed to poison
71 // the whole region - it may poison only subregion of [addr, addr+size) due
72 // to ASan alignment restrictions.
73 // Method is NOT thread-safe in the sense that no two threads can
74 // (un)poison memory in the same memory region simultaneously.
75 void __asan_poison_memory_region(void const volatile *addr
, uptr size
)
76 SANITIZER_INTERFACE_ATTRIBUTE
;
77 // Marks memory region [addr, addr+size) as addressable.
78 // This memory must be previously allocated by the user program. Accessing
79 // addresses in this region is allowed until this region is poisoned again.
80 // This function may unpoison a superregion of [addr, addr+size) due to
81 // ASan alignment restrictions.
82 // Method is NOT thread-safe in the sense that no two threads can
83 // (un)poison memory in the same memory region simultaneously.
84 void __asan_unpoison_memory_region(void const volatile *addr
, uptr size
)
85 SANITIZER_INTERFACE_ATTRIBUTE
;
87 // Performs cleanup before a NoReturn function. Must be called before things
88 // like _exit and execl to avoid false positives on stack.
89 void __asan_handle_no_return() SANITIZER_INTERFACE_ATTRIBUTE
;
91 // User code should use macro instead of functions.
92 #if __has_feature(address_sanitizer)
93 #define ASAN_POISON_MEMORY_REGION(addr, size) \
94 __asan_poison_memory_region((addr), (size))
95 #define ASAN_UNPOISON_MEMORY_REGION(addr, size) \
96 __asan_unpoison_memory_region((addr), (size))
98 #define ASAN_POISON_MEMORY_REGION(addr, size) \
99 ((void)(addr), (void)(size))
100 #define ASAN_UNPOISON_MEMORY_REGION(addr, size) \
101 ((void)(addr), (void)(size))
104 // Returns true iff addr is poisoned (i.e. 1-byte read/write access to this
105 // address will result in error report from AddressSanitizer).
106 bool __asan_address_is_poisoned(void const volatile *addr
)
107 SANITIZER_INTERFACE_ATTRIBUTE
;
109 // This is an internal function that is called to report an error.
110 // However it is still a part of the interface because users may want to
111 // set a breakpoint on this function in a debugger.
112 void __asan_report_error(uptr pc
, uptr bp
, uptr sp
,
113 uptr addr
, bool is_write
, uptr access_size
)
114 SANITIZER_INTERFACE_ATTRIBUTE
;
116 // Sets the exit code to use when reporting an error.
117 // Returns the old value.
118 int __asan_set_error_exit_code(int exit_code
)
119 SANITIZER_INTERFACE_ATTRIBUTE
;
121 // Sets the callback to be called right before death on error.
122 // Passing 0 will unset the callback.
123 void __asan_set_death_callback(void (*callback
)(void))
124 SANITIZER_INTERFACE_ATTRIBUTE
;
126 void __asan_set_error_report_callback(void (*callback
)(const char*))
127 SANITIZER_INTERFACE_ATTRIBUTE
;
129 // User may provide function that would be called right when ASan detects
130 // an error. This can be used to notice cases when ASan detects an error, but
131 // the program crashes before ASan report is printed.
132 void __asan_on_error()
133 SANITIZER_WEAK_ATTRIBUTE SANITIZER_INTERFACE_ATTRIBUTE
;
135 // User may provide its own implementation for symbolization function.
136 // It should print the description of instruction at address "pc" to
137 // "out_buffer". Description should be at most "out_size" bytes long.
138 // User-specified function should return true if symbolization was
140 bool __asan_symbolize(const void *pc
, char *out_buffer
, int out_size
)
141 SANITIZER_WEAK_ATTRIBUTE SANITIZER_INTERFACE_ATTRIBUTE
;
143 // Returns the estimated number of bytes that will be reserved by allocator
144 // for request of "size" bytes. If ASan allocator can't allocate that much
145 // memory, returns the maximal possible allocation size, otherwise returns
147 uptr
__asan_get_estimated_allocated_size(uptr size
)
148 SANITIZER_INTERFACE_ATTRIBUTE
;
149 // Returns true if p was returned by the ASan allocator and
151 bool __asan_get_ownership(const void *p
)
152 SANITIZER_INTERFACE_ATTRIBUTE
;
153 // Returns the number of bytes reserved for the pointer p.
154 // Requires (get_ownership(p) == true) or (p == 0).
155 uptr
__asan_get_allocated_size(const void *p
)
156 SANITIZER_INTERFACE_ATTRIBUTE
;
157 // Number of bytes, allocated and not yet freed by the application.
158 uptr
__asan_get_current_allocated_bytes()
159 SANITIZER_INTERFACE_ATTRIBUTE
;
160 // Number of bytes, mmaped by asan allocator to fulfill allocation requests.
161 // Generally, for request of X bytes, allocator can reserve and add to free
162 // lists a large number of chunks of size X to use them for future requests.
163 // All these chunks count toward the heap size. Currently, allocator never
164 // releases memory to OS (instead, it just puts freed chunks to free lists).
165 uptr
__asan_get_heap_size()
166 SANITIZER_INTERFACE_ATTRIBUTE
;
167 // Number of bytes, mmaped by asan allocator, which can be used to fulfill
168 // allocation requests. When a user program frees memory chunk, it can first
169 // fall into quarantine and will count toward __asan_get_free_bytes() later.
170 uptr
__asan_get_free_bytes()
171 SANITIZER_INTERFACE_ATTRIBUTE
;
172 // Number of bytes in unmapped pages, that are released to OS. Currently,
174 uptr
__asan_get_unmapped_bytes()
175 SANITIZER_INTERFACE_ATTRIBUTE
;
176 // Prints accumulated stats to stderr. Used for debugging.
177 void __asan_print_accumulated_stats()
178 SANITIZER_INTERFACE_ATTRIBUTE
;
180 // This function may be overriden by user to provide a string containing
181 // ASan runtime options. See asan_flags.h for details.
182 const char* __asan_default_options()
183 SANITIZER_WEAK_ATTRIBUTE SANITIZER_INTERFACE_ATTRIBUTE
;
185 // Malloc hooks that may be overriden by user.
186 // __asan_malloc_hook(ptr, size) is called immediately after
187 // allocation of "size" bytes, which returned "ptr".
188 // __asan_free_hook(ptr) is called immediately before
189 // deallocation of "ptr".
190 // If user doesn't provide implementations of these hooks, they are no-op.
191 void __asan_malloc_hook(void *ptr
, uptr size
)
192 SANITIZER_WEAK_ATTRIBUTE SANITIZER_INTERFACE_ATTRIBUTE
;
193 void __asan_free_hook(void *ptr
)
194 SANITIZER_WEAK_ATTRIBUTE SANITIZER_INTERFACE_ATTRIBUTE
;
197 #endif // SANITIZER_ASAN_INTERFACE_H