interception.h revision b66bfd1e28776f0a350b9c197926c2c172678603
15b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov//===-- interception.h ------------------------------------------*- C++ -*-===// 25b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// 35b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// The LLVM Compiler Infrastructure 45b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// 55b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// This file is distributed under the University of Illinois Open Source 65b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// License. See LICENSE.TXT for details. 75b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// 85b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov//===----------------------------------------------------------------------===// 95b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// 105b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// This file is a part of AddressSanitizer, an address sanity checker. 115b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// 125b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// Machinery for providing replacements/wrappers for system functions. 135b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov//===----------------------------------------------------------------------===// 145b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 155b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#ifndef INTERCEPTION_H 165b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#define INTERCEPTION_H 175b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 185b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#if !defined(__linux__) && !defined(__APPLE__) && !defined(_WIN32) 195b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov# error "Interception doesn't work on this operating system." 205b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#endif 215b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 225b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// How to use this library: 235b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// 1) Include this header to define your own interceptors 245b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// (see details below). 255b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// 2) Build all *.cc files and link against them. 265b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// On Mac you will also need to: 275b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// 3) Provide your own implementation for the following functions: 285b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// mach_error_t __interception::allocate_island(void **ptr, 295b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// size_t size, 305b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// void *hint); 315b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// mach_error_t __interception::deallocate_island(void *ptr); 325b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// See "interception_mac.h" for more details. 335b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 345b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// How to add an interceptor: 355b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// Suppose you need to wrap/replace system function (generally, from libc): 365b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// int foo(const char *bar, double baz); 375b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// You'll need to: 385b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// 1) define INTERCEPTOR(int, foo, const char *bar, double baz) { ... } in 395b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// your source file. 405b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// 2) Call "INTERCEPT_FUNCTION(foo)" prior to the first call of "foo". 415b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// INTERCEPT_FUNCTION(foo) evaluates to "true" iff the function was 425b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// intercepted successfully. 435b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// You can access original function by calling REAL(foo)(bar, baz). 445b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// By default, REAL(foo) will be visible only inside your interceptor, and if 455b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// you want to use it in other parts of RTL, you'll need to: 46b4fefa713da3dabda1cd83ae4182c71f1683f02cAlexey Samsonov// 3a) add DECLARE_REAL(int, foo, const char*, double) to a 475b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// header file. 485b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// However, if the call "INTERCEPT_FUNCTION(foo)" and definition for 495b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// INTERCEPTOR(..., foo, ...) are in different files, you'll instead need to: 50b4fefa713da3dabda1cd83ae4182c71f1683f02cAlexey Samsonov// 3b) add DECLARE_REAL_AND_INTERCEPTOR(int, foo, const char*, double) 515b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// to a header file. 525b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 535b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// Notes: 1. Things may not work properly if macro INTERCEPT(...) {...} or 54b4fefa713da3dabda1cd83ae4182c71f1683f02cAlexey Samsonov// DECLARE_REAL(...) are located inside namespaces. 555b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// 2. On Mac you can also use: "OVERRIDE_FUNCTION(foo, zoo);" to 565b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// effectively redirect calls from "foo" to "zoo". In this case 575b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// you aren't required to implement 58b4fefa713da3dabda1cd83ae4182c71f1683f02cAlexey Samsonov// INTERCEPTOR(int, foo, const char *bar, double baz) {...} 595b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// but instead you'll have to add 60b4fefa713da3dabda1cd83ae4182c71f1683f02cAlexey Samsonov// DEFINE_REAL(int, foo, const char *bar, double baz) in your 615b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// source file (to define a pointer to overriden function). 625b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 635b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// How it works: 64580469d7e40e39319cb2d3750edac4bccca18105Dmitry Vyukov// To replace system functions on Linux we just need to declare functions 655b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// with same names in our library and then obtain the real function pointers 66580469d7e40e39319cb2d3750edac4bccca18105Dmitry Vyukov// using dlsym(). 67580469d7e40e39319cb2d3750edac4bccca18105Dmitry Vyukov// There is one complication. A user may also intercept some of the functions 68f54c0e3321e2381fca3f02faefaaa6639d59c7cfDmitry Vyukov// we intercept. To resolve this we declare our interceptors with __interceptor_ 69f54c0e3321e2381fca3f02faefaaa6639d59c7cfDmitry Vyukov// prefix, and then make actual interceptors weak aliases to __interceptor_ 70580469d7e40e39319cb2d3750edac4bccca18105Dmitry Vyukov// functions. 71580469d7e40e39319cb2d3750edac4bccca18105Dmitry Vyukov// This is not so on Mac OS, where the two-level namespace makes 725b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// our replacement functions invisible to other libraries. This may be overcomed 735b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// using the DYLD_FORCE_FLAT_NAMESPACE, but some errors loading the shared 74580469d7e40e39319cb2d3750edac4bccca18105Dmitry Vyukov// libraries in Chromium were noticed when doing so. Instead we use 75580469d7e40e39319cb2d3750edac4bccca18105Dmitry Vyukov// mach_override, a handy framework for patching functions at runtime. 76580469d7e40e39319cb2d3750edac4bccca18105Dmitry Vyukov// To avoid possible name clashes, our replacement functions have 775b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov// the "wrap_" prefix on Mac. 780ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko// An alternative to function patching is to create a dylib containing a 790ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko// __DATA,__interpose section that associates library functions with their 800ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko// wrappers. When this dylib is preloaded before an executable using 810ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko// DYLD_INSERT_LIBRARIES, it routes all the calls to interposed functions done 820ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko// through stubs to the wrapper functions. Such a library is built with 830ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko// -DMAC_INTERPOSE_FUNCTIONS=1. 840ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko 850ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko#if !defined(MAC_INTERPOSE_FUNCTIONS) || !defined(__APPLE__) 860ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko# define MAC_INTERPOSE_FUNCTIONS 0 870ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko#endif 885b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 895b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#if defined(__APPLE__) 905b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov# define WRAP(x) wrap_##x 915b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov# define WRAPPER_NAME(x) "wrap_"#x 925b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov# define INTERCEPTOR_ATTRIBUTE 93b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov# define DECLARE_WRAPPER(ret_type, func, ...) 945b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#elif defined(_WIN32) 952716a61d085a8fdf13a099822720e320414cc4dcTimur Iskhodzhanov# if defined(_DLL) // DLL CRT 962716a61d085a8fdf13a099822720e320414cc4dcTimur Iskhodzhanov# define WRAP(x) x 972716a61d085a8fdf13a099822720e320414cc4dcTimur Iskhodzhanov# define WRAPPER_NAME(x) #x 982716a61d085a8fdf13a099822720e320414cc4dcTimur Iskhodzhanov# define INTERCEPTOR_ATTRIBUTE 992716a61d085a8fdf13a099822720e320414cc4dcTimur Iskhodzhanov# else // Static CRT 1002716a61d085a8fdf13a099822720e320414cc4dcTimur Iskhodzhanov# define WRAP(x) wrap_##x 1012716a61d085a8fdf13a099822720e320414cc4dcTimur Iskhodzhanov# define WRAPPER_NAME(x) "wrap_"#x 1022716a61d085a8fdf13a099822720e320414cc4dcTimur Iskhodzhanov# define INTERCEPTOR_ATTRIBUTE 1032716a61d085a8fdf13a099822720e320414cc4dcTimur Iskhodzhanov# endif 104b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov# define DECLARE_WRAPPER(ret_type, func, ...) 1055b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#else 106f54c0e3321e2381fca3f02faefaaa6639d59c7cfDmitry Vyukov# define WRAP(x) __interceptor_ ## x 107f54c0e3321e2381fca3f02faefaaa6639d59c7cfDmitry Vyukov# define WRAPPER_NAME(x) "__interceptor_" #x 1085b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov# define INTERCEPTOR_ATTRIBUTE __attribute__((visibility("default"))) 109b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov# define DECLARE_WRAPPER(ret_type, func, ...) \ 110b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov extern "C" ret_type func(__VA_ARGS__) \ 111ba362a7f0e98b369758f07aec8794c61e688b82dAlexey Samsonov __attribute__((weak, alias("__interceptor_" #func), visibility("default"))); 1125b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#endif 1135b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 1140ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko#if !MAC_INTERPOSE_FUNCTIONS 1150ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko# define PTR_TO_REAL(x) real_##x 1160ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko# define REAL(x) __interception::PTR_TO_REAL(x) 1170ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko# define FUNC_TYPE(x) x##_f 1180ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko 1190ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko# define DECLARE_REAL(ret_type, func, ...) \ 1200ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko typedef ret_type (*FUNC_TYPE(func))(__VA_ARGS__); \ 1210ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko namespace __interception { \ 1220ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko extern FUNC_TYPE(func) PTR_TO_REAL(func); \ 1230ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko } 1240ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko#else // MAC_INTERPOSE_FUNCTIONS 1250ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko# define REAL(x) x 1260ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko# define DECLARE_REAL(ret_type, func, ...) \ 1270ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko extern "C" ret_type func(__VA_ARGS__); 1280ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko#endif // MAC_INTERPOSE_FUNCTIONS 1295b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 1306bae39d1db13f60d3e9b8393e5b9d9eb2ab1b5c0Chandler Carruth#define DECLARE_REAL_AND_INTERCEPTOR(ret_type, func, ...) \ 131ba362a7f0e98b369758f07aec8794c61e688b82dAlexey Samsonov DECLARE_REAL(ret_type, func, ##__VA_ARGS__) \ 1325b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov extern "C" ret_type WRAP(func)(__VA_ARGS__); 1335b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 134b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov// Generally, you don't need to use DEFINE_REAL by itself, as INTERCEPTOR 135b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov// macros does its job. In exceptional cases you may need to call REAL(foo) 136b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov// without defining INTERCEPTOR(..., foo, ...). For example, if you override 137b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov// foo with an interceptor for other function. 1380ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko#if !MAC_INTERPOSE_FUNCTIONS 139b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov# define DEFINE_REAL(ret_type, func, ...) \ 140b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov typedef ret_type (*FUNC_TYPE(func))(__VA_ARGS__); \ 1410ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko namespace __interception { \ 1420ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko FUNC_TYPE(func) PTR_TO_REAL(func); \ 1430ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko } 1440ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko#else 145b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov# define DEFINE_REAL(ret_type, func, ...) 1460ef531054fc25c11e372cbab1384f10954984219Alexander Potapenko#endif 147600972e3427173cc8904d741decd1af0ed5de9fdTimur Iskhodzhanov 148b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov#define INTERCEPTOR(ret_type, func, ...) \ 149b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov DEFINE_REAL(ret_type, func, __VA_ARGS__) \ 150b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov DECLARE_WRAPPER(ret_type, func, __VA_ARGS__) \ 1515b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov extern "C" \ 1525b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov INTERCEPTOR_ATTRIBUTE \ 153b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov ret_type WRAP(func)(__VA_ARGS__) 154600972e3427173cc8904d741decd1af0ed5de9fdTimur Iskhodzhanov 155600972e3427173cc8904d741decd1af0ed5de9fdTimur Iskhodzhanov#if defined(_WIN32) 156600972e3427173cc8904d741decd1af0ed5de9fdTimur Iskhodzhanov# define INTERCEPTOR_WINAPI(ret_type, func, ...) \ 157b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov typedef ret_type (__stdcall *FUNC_TYPE(func))(__VA_ARGS__); \ 158b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov namespace __interception { \ 159b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov FUNC_TYPE(func) PTR_TO_REAL(func); \ 160b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov } \ 161b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov DECLARE_WRAPPER(ret_type, func, __VA_ARGS__) \ 162b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov extern "C" \ 163b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov INTERCEPTOR_ATTRIBUTE \ 164b66bfd1e28776f0a350b9c197926c2c172678603Alexey Samsonov ret_type __stdcall WRAP(func)(__VA_ARGS__) 165600972e3427173cc8904d741decd1af0ed5de9fdTimur Iskhodzhanov#endif 1665b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 167592d3f707e02968c75fd6e90d06d24f5df99c8b9Alexey Samsonov// ISO C++ forbids casting between pointer-to-function and pointer-to-object, 168592d3f707e02968c75fd6e90d06d24f5df99c8b9Alexey Samsonov// so we use casting via an integral type __interception::uptr, 169592d3f707e02968c75fd6e90d06d24f5df99c8b9Alexey Samsonov// assuming that system is POSIX-compliant. Using other hacks seem 170592d3f707e02968c75fd6e90d06d24f5df99c8b9Alexey Samsonov// challenging, as we don't even pass function type to 171592d3f707e02968c75fd6e90d06d24f5df99c8b9Alexey Samsonov// INTERCEPT_FUNCTION macro, only its name. 172592d3f707e02968c75fd6e90d06d24f5df99c8b9Alexey Samsonovnamespace __interception { 173592d3f707e02968c75fd6e90d06d24f5df99c8b9Alexey Samsonovtypedef unsigned long uptr; // NOLINT 174592d3f707e02968c75fd6e90d06d24f5df99c8b9Alexey Samsonov} // namespace __interception 175592d3f707e02968c75fd6e90d06d24f5df99c8b9Alexey Samsonov 1765b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#define INCLUDED_FROM_INTERCEPTION_LIB 1775b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 1785b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#if defined(__linux__) 1795b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov# include "interception_linux.h" 1805b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov# define INTERCEPT_FUNCTION(func) INTERCEPT_FUNCTION_LINUX(func) 1815b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#elif defined(__APPLE__) 1825b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov# include "interception_mac.h" 1835b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov# define OVERRIDE_FUNCTION(old_func, new_func) \ 1845b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov OVERRIDE_FUNCTION_MAC(old_func, new_func) 1855b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov# define INTERCEPT_FUNCTION(func) INTERCEPT_FUNCTION_MAC(func) 1865b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#else // defined(_WIN32) 18707bb9f1e3600195119aec1aae1aa48a6ed2f5febTimur Iskhodzhanov# include "interception_win.h" 18807bb9f1e3600195119aec1aae1aa48a6ed2f5febTimur Iskhodzhanov# define INTERCEPT_FUNCTION(func) INTERCEPT_FUNCTION_WIN(func) 1895b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#endif 1905b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 1915b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#undef INCLUDED_FROM_INTERCEPTION_LIB 1925b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov 1935b29018cf422e7711fb760b733c32127397a43fcAlexey Samsonov#endif // INTERCEPTION_H 194