1d865fecddccebf898ceed24d096fc58fb29a6e57Chandler Carruth//===-- sanitizer/asan_interface.h ------------------------------*- C++ -*-===// 21e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany// 31e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany// The LLVM Compiler Infrastructure 41e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany// 51e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany// This file is distributed under the University of Illinois Open Source 61e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany// License. See LICENSE.TXT for details. 71e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany// 81e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany//===----------------------------------------------------------------------===// 91e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany// 10c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov// This file is a part of AddressSanitizer. 111e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany// 12c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov// Public interface header. 131e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany//===----------------------------------------------------------------------===// 14d865fecddccebf898ceed24d096fc58fb29a6e57Chandler Carruth#ifndef SANITIZER_ASAN_INTERFACE_H 15d865fecddccebf898ceed24d096fc58fb29a6e57Chandler Carruth#define SANITIZER_ASAN_INTERFACE_H 16d865fecddccebf898ceed24d096fc58fb29a6e57Chandler Carruth 17d865fecddccebf898ceed24d096fc58fb29a6e57Chandler Carruth#include <sanitizer/common_interface_defs.h> 181e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany 19c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov#ifdef __cplusplus 201e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryanyextern "C" { 21c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov#endif 221e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // Marks memory region [addr, addr+size) as unaddressable. 231e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // This memory must be previously allocated by the user program. Accessing 241e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // addresses in this region from instrumented code is forbidden until 251e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // this region is unpoisoned. This function is not guaranteed to poison 261e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // the whole region - it may poison only subregion of [addr, addr+size) due 271e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // to ASan alignment restrictions. 281e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // Method is NOT thread-safe in the sense that no two threads can 291e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // (un)poison memory in the same memory region simultaneously. 30c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov void __asan_poison_memory_region(void const volatile *addr, size_t size); 311e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // Marks memory region [addr, addr+size) as addressable. 321e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // This memory must be previously allocated by the user program. Accessing 331e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // addresses in this region is allowed until this region is poisoned again. 341e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // This function may unpoison a superregion of [addr, addr+size) due to 351e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // ASan alignment restrictions. 361e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // Method is NOT thread-safe in the sense that no two threads can 371e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // (un)poison memory in the same memory region simultaneously. 38c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov void __asan_unpoison_memory_region(void const volatile *addr, size_t size); 39f54b1f9b73a6855d77ee270c282bd61407fa73a0Kostya Serebryany 40e31eca900a1f8849af75100c2d92e838d79d0920Kostya Serebryany// User code should use macros instead of functions. 41e31eca900a1f8849af75100c2d92e838d79d0920Kostya Serebryany#if __has_feature(address_sanitizer) || defined(__SANITIZE_ADDRESS__) 421e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany#define ASAN_POISON_MEMORY_REGION(addr, size) \ 431e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany __asan_poison_memory_region((addr), (size)) 441e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany#define ASAN_UNPOISON_MEMORY_REGION(addr, size) \ 451e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany __asan_unpoison_memory_region((addr), (size)) 461e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany#else 471e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany#define ASAN_POISON_MEMORY_REGION(addr, size) \ 481e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany ((void)(addr), (void)(size)) 491e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany#define ASAN_UNPOISON_MEMORY_REGION(addr, size) \ 501e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany ((void)(addr), (void)(size)) 511e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany#endif 521e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany 532d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines // Returns 1 if addr is poisoned (i.e. 1-byte read/write access to this 541e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // address will result in error report from AddressSanitizer). 552d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines // Otherwise returns 0. 562d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines int __asan_address_is_poisoned(void const volatile *addr); 571e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany 586d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // If at least one byte in [beg, beg+size) is poisoned, return the address 59681e775893cc85c5f0c7dd48e30494323fff1580Kostya Serebryany // of the first such byte. Otherwise return 0. 60c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov void *__asan_region_is_poisoned(void *beg, size_t size); 61681e775893cc85c5f0c7dd48e30494323fff1580Kostya Serebryany 6217a7c6763224300f6740b5e7fae274734afec675Kostya Serebryany // Print the description of addr (useful when debugging in gdb). 63c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov void __asan_describe_address(void *addr); 6417a7c6763224300f6740b5e7fae274734afec675Kostya Serebryany 656d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // Useful for calling from a debugger to get information about an ASan error. 666d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // Returns 1 if an error has been (or is being) reported, otherwise returns 0. 676d1862363c88c183b0ed7740fca876342cf0474bStephen Hines int __asan_report_present(); 686d1862363c88c183b0ed7740fca876342cf0474bStephen Hines 696d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // Useful for calling from a debugger to get information about an ASan error. 706d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // If an error has been (or is being) reported, the following functions return 716d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // the pc, bp, sp, address, access type (0 = read, 1 = write), access size and 726d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // bug description (e.g. "heap-use-after-free"). Otherwise they return 0. 736d1862363c88c183b0ed7740fca876342cf0474bStephen Hines void *__asan_get_report_pc(); 746d1862363c88c183b0ed7740fca876342cf0474bStephen Hines void *__asan_get_report_bp(); 756d1862363c88c183b0ed7740fca876342cf0474bStephen Hines void *__asan_get_report_sp(); 766d1862363c88c183b0ed7740fca876342cf0474bStephen Hines void *__asan_get_report_address(); 776d1862363c88c183b0ed7740fca876342cf0474bStephen Hines int __asan_get_report_access_type(); 786d1862363c88c183b0ed7740fca876342cf0474bStephen Hines size_t __asan_get_report_access_size(); 796d1862363c88c183b0ed7740fca876342cf0474bStephen Hines const char *__asan_get_report_description(); 806d1862363c88c183b0ed7740fca876342cf0474bStephen Hines 816d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // Useful for calling from the debugger to get information about a pointer. 826d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // Returns the category of the given pointer as a constant string. 836d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // Possible return values are "global", "stack", "stack-fake", "heap", 846d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // "heap-invalid", "shadow-low", "shadow-gap", "shadow-high", "unknown". 856d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // If global or stack, tries to also return the variable name, address and 866d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // size. If heap, tries to return the chunk address and size. 'name' should 876d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // point to an allocated buffer of size 'name_size'. 886d1862363c88c183b0ed7740fca876342cf0474bStephen Hines const char *__asan_locate_address(void *addr, char *name, size_t name_size, 896d1862363c88c183b0ed7740fca876342cf0474bStephen Hines void **region_address, size_t *region_size); 906d1862363c88c183b0ed7740fca876342cf0474bStephen Hines 916d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // Useful for calling from the debugger to get the allocation stack trace 926d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // and thread ID for a heap address. Stores up to 'size' frames into 'trace', 936d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // returns the number of stored frames or 0 on error. 946d1862363c88c183b0ed7740fca876342cf0474bStephen Hines size_t __asan_get_alloc_stack(void *addr, void **trace, size_t size, 956d1862363c88c183b0ed7740fca876342cf0474bStephen Hines int *thread_id); 966d1862363c88c183b0ed7740fca876342cf0474bStephen Hines 976d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // Useful for calling from the debugger to get the free stack trace 986d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // and thread ID for a heap address. Stores up to 'size' frames into 'trace', 996d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // returns the number of stored frames or 0 on error. 1006d1862363c88c183b0ed7740fca876342cf0474bStephen Hines size_t __asan_get_free_stack(void *addr, void **trace, size_t size, 1016d1862363c88c183b0ed7740fca876342cf0474bStephen Hines int *thread_id); 1026d1862363c88c183b0ed7740fca876342cf0474bStephen Hines 1036d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // Useful for calling from the debugger to get the current shadow memory 1046d1862363c88c183b0ed7740fca876342cf0474bStephen Hines // mapping. 1056d1862363c88c183b0ed7740fca876342cf0474bStephen Hines void __asan_get_shadow_mapping(size_t *shadow_scale, size_t *shadow_offset); 1066d1862363c88c183b0ed7740fca876342cf0474bStephen Hines 1071e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // This is an internal function that is called to report an error. 1081e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // However it is still a part of the interface because users may want to 1091e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // set a breakpoint on this function in a debugger. 110c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov void __asan_report_error(void *pc, void *bp, void *sp, 1112d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines void *addr, int is_write, size_t access_size); 1121e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany 1131e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // Sets the exit code to use when reporting an error. 1141e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // Returns the old value. 115c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov int __asan_set_error_exit_code(int exit_code); 116e1fe0fd868886b53cb8d5d957afebbdd47688df7Kostya Serebryany 11786277eb844c4983c81de62d7c050e92fe7155788Stephen Hines // Deprecated. Call __sanitizer_set_death_callback instead. 118c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov void __asan_set_death_callback(void (*callback)(void)); 1191e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany 120c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov void __asan_set_error_report_callback(void (*callback)(const char*)); 1213fe913558354f76707e2c5584559521399854b79Alexander Potapenko 122866334332ff8c2a1b7f3715224614b6b75a7578cAlexey Samsonov // User may provide function that would be called right when ASan detects 123866334332ff8c2a1b7f3715224614b6b75a7578cAlexey Samsonov // an error. This can be used to notice cases when ASan detects an error, but 124866334332ff8c2a1b7f3715224614b6b75a7578cAlexey Samsonov // the program crashes before ASan report is printed. 125c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov void __asan_on_error(); 126f657a1977b6053c76ca8393f574da7593ea3ea12Alexey Samsonov 1271e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany // Prints accumulated stats to stderr. Used for debugging. 128c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov void __asan_print_accumulated_stats(); 129c58b57eac9cc1a495f3c8ffa5fe4a5cf55e96a6aAlexey Samsonov 1306a08d29b2020004b801ca69d8aea5872a7e67d72Alexey Samsonov // This function may be optionally provided by user and should return 1316a08d29b2020004b801ca69d8aea5872a7e67d72Alexey Samsonov // a string containing ASan runtime options. See asan_flags.h for details. 132c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov const char* __asan_default_options(); 133b21de9e71522a7f9ed31fd92aafe6936873a971cAlexey Samsonov 1342d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines // The following 2 functions facilitate garbage collection in presence of 1352d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines // asan's fake stack. 1362d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines 1372d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines // Returns an opaque handler to be used later in __asan_addr_is_in_fake_stack. 1382d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines // Returns NULL if the current thread does not have a fake stack. 1392d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines void *__asan_get_current_fake_stack(); 1402d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines 1412d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines // If fake_stack is non-NULL and addr belongs to a fake frame in 1422d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines // fake_stack, returns the address on real stack that corresponds to 1432d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines // the fake frame and sets beg/end to the boundaries of this fake frame. 1442d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines // Otherwise returns NULL and does not touch beg/end. 1452d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines // If beg/end are NULL, they are not touched. 1462d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines // This function may be called from a thread other than the owner of 1472d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines // fake_stack, but the owner thread need to be alive. 1482d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines void *__asan_addr_is_in_fake_stack(void *fake_stack, void *addr, void **beg, 1492d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines void **end); 1502d1fdb26e458c4ddc04155c1d421bced3ba90cd0Stephen Hines 151c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov#ifdef __cplusplus 152c58b57eac9cc1a495f3c8ffa5fe4a5cf55e96a6aAlexey Samsonov} // extern "C" 153c70fa28caaaec2134f2c2230821fcc0f0d7ac27eAlexey Samsonov#endif 1541e172b4bdec57329bf904f063a29f99cddf2d85fKostya Serebryany 155d865fecddccebf898ceed24d096fc58fb29a6e57Chandler Carruth#endif // SANITIZER_ASAN_INTERFACE_H 156