Home | History | Annotate | Download | only in interception
      1 //===-- interception.h ------------------------------------------*- C++ -*-===//
      2 //
      3 //                     The LLVM Compiler Infrastructure
      4 //
      5 // This file is distributed under the University of Illinois Open Source
      6 // License. See LICENSE.TXT for details.
      7 //
      8 //===----------------------------------------------------------------------===//
      9 //
     10 // This file is a part of AddressSanitizer, an address sanity checker.
     11 //
     12 // Machinery for providing replacements/wrappers for system functions.
     13 //===----------------------------------------------------------------------===//
     14 
     15 #ifndef INTERCEPTION_H
     16 #define INTERCEPTION_H
     17 
     18 #if !defined(__linux__) && !defined(__FreeBSD__) && \
     19   !defined(__APPLE__) && !defined(_WIN32)
     20 # error "Interception doesn't work on this operating system."
     21 #endif
     22 
     23 #include "sanitizer_common/sanitizer_internal_defs.h"
     24 
     25 // These typedefs should be used only in the interceptor definitions to replace
     26 // the standard system types (e.g. SSIZE_T instead of ssize_t)
     27 typedef __sanitizer::uptr    SIZE_T;
     28 typedef __sanitizer::sptr    SSIZE_T;
     29 typedef __sanitizer::sptr    PTRDIFF_T;
     30 typedef __sanitizer::s64     INTMAX_T;
     31 typedef __sanitizer::OFF_T   OFF_T;
     32 typedef __sanitizer::OFF64_T OFF64_T;
     33 
     34 // How to add an interceptor:
     35 // Suppose you need to wrap/replace system function (generally, from libc):
     36 //      int foo(const char *bar, double baz);
     37 // You'll need to:
     38 //      1) define INTERCEPTOR(int, foo, const char *bar, double baz) { ... } in
     39 //         your source file. See the notes below for cases when
     40 //         INTERCEPTOR_WITH_SUFFIX(...) should be used instead.
     41 //      2) Call "INTERCEPT_FUNCTION(foo)" prior to the first call of "foo".
     42 //         INTERCEPT_FUNCTION(foo) evaluates to "true" iff the function was
     43 //         intercepted successfully.
     44 // You can access original function by calling REAL(foo)(bar, baz).
     45 // By default, REAL(foo) will be visible only inside your interceptor, and if
     46 // you want to use it in other parts of RTL, you'll need to:
     47 //      3a) add DECLARE_REAL(int, foo, const char*, double) to a
     48 //          header file.
     49 // However, if the call "INTERCEPT_FUNCTION(foo)" and definition for
     50 // INTERCEPTOR(..., foo, ...) are in different files, you'll instead need to:
     51 //      3b) add DECLARE_REAL_AND_INTERCEPTOR(int, foo, const char*, double)
     52 //          to a header file.
     53 
     54 // Notes: 1. Things may not work properly if macro INTERCEPTOR(...) {...} or
     55 //           DECLARE_REAL(...) are located inside namespaces.
     56 //        2. On Mac you can also use: "OVERRIDE_FUNCTION(foo, zoo)" to
     57 //           effectively redirect calls from "foo" to "zoo". In this case
     58 //           you aren't required to implement
     59 //           INTERCEPTOR(int, foo, const char *bar, double baz) {...}
     60 //           but instead you'll have to add
     61 //           DECLARE_REAL(int, foo, const char *bar, double baz) in your
     62 //           source file (to define a pointer to overriden function).
     63 //        3. Some Mac functions have symbol variants discriminated by
     64 //           additional suffixes, e.g. _$UNIX2003 (see
     65 //           https://developer.apple.com/library/mac/#releasenotes/Darwin/SymbolVariantsRelNotes/index.html
     66 //           for more details). To intercept such functions you need to use the
     67 //           INTERCEPTOR_WITH_SUFFIX(...) macro.
     68 
     69 // How it works:
     70 // To replace system functions on Linux we just need to declare functions
     71 // with same names in our library and then obtain the real function pointers
     72 // using dlsym().
     73 // There is one complication. A user may also intercept some of the functions
     74 // we intercept. To resolve this we declare our interceptors with __interceptor_
     75 // prefix, and then make actual interceptors weak aliases to __interceptor_
     76 // functions.
     77 //
     78 // This is not so on Mac OS, where the two-level namespace makes
     79 // our replacement functions invisible to other libraries. This may be overcomed
     80 // using the DYLD_FORCE_FLAT_NAMESPACE, but some errors loading the shared
     81 // libraries in Chromium were noticed when doing so.
     82 // Instead we create a dylib containing a __DATA,__interpose section that
     83 // associates library functions with their wrappers. When this dylib is
     84 // preloaded before an executable using DYLD_INSERT_LIBRARIES, it routes all
     85 // the calls to interposed functions done through stubs to the wrapper
     86 // functions.
     87 // As it's decided at compile time which functions are to be intercepted on Mac,
     88 // INTERCEPT_FUNCTION() is effectively a no-op on this system.
     89 
     90 #if defined(__APPLE__)
     91 #include <sys/cdefs.h>  // For __DARWIN_ALIAS_C().
     92 
     93 // Just a pair of pointers.
     94 struct interpose_substitution {
     95   const uptr replacement;
     96   const uptr original;
     97 };
     98 
     99 // For a function foo() create a global pair of pointers { wrap_foo, foo } in
    100 // the __DATA,__interpose section.
    101 // As a result all the calls to foo() will be routed to wrap_foo() at runtime.
    102 #define INTERPOSER(func_name) __attribute__((used)) \
    103 const interpose_substitution substitution_##func_name[] \
    104     __attribute__((section("__DATA, __interpose"))) = { \
    105     { reinterpret_cast<const uptr>(WRAP(func_name)), \
    106       reinterpret_cast<const uptr>(func_name) } \
    107 }
    108 
    109 // For a function foo() and a wrapper function bar() create a global pair
    110 // of pointers { bar, foo } in the __DATA,__interpose section.
    111 // As a result all the calls to foo() will be routed to bar() at runtime.
    112 #define INTERPOSER_2(func_name, wrapper_name) __attribute__((used)) \
    113 const interpose_substitution substitution_##func_name[] \
    114     __attribute__((section("__DATA, __interpose"))) = { \
    115     { reinterpret_cast<const uptr>(wrapper_name), \
    116       reinterpret_cast<const uptr>(func_name) } \
    117 }
    118 
    119 # define WRAP(x) wrap_##x
    120 # define WRAPPER_NAME(x) "wrap_"#x
    121 # define INTERCEPTOR_ATTRIBUTE
    122 # define DECLARE_WRAPPER(ret_type, func, ...)
    123 
    124 #elif defined(_WIN32)
    125 # if defined(_DLL)  // DLL CRT
    126 #  define WRAP(x) x
    127 #  define WRAPPER_NAME(x) #x
    128 #  define INTERCEPTOR_ATTRIBUTE
    129 # else  // Static CRT
    130 #  define WRAP(x) __asan_wrap_##x
    131 #  define WRAPPER_NAME(x) "__asan_wrap_"#x
    132 #  define INTERCEPTOR_ATTRIBUTE __declspec(dllexport)
    133 # endif
    134 # define DECLARE_WRAPPER(ret_type, func, ...) \
    135     extern "C" ret_type func(__VA_ARGS__);
    136 # define DECLARE_WRAPPER_WINAPI(ret_type, func, ...) \
    137     extern "C" __declspec(dllimport) ret_type __stdcall func(__VA_ARGS__);
    138 #elif defined(__FreeBSD__)
    139 # define WRAP(x) __interceptor_ ## x
    140 # define WRAPPER_NAME(x) "__interceptor_" #x
    141 # define INTERCEPTOR_ATTRIBUTE __attribute__((visibility("default")))
    142 // FreeBSD's dynamic linker (incompliantly) gives non-weak symbols higher
    143 // priority than weak ones so weak aliases won't work for indirect calls
    144 // in position-independent (-fPIC / -fPIE) mode.
    145 # define DECLARE_WRAPPER(ret_type, func, ...) \
    146      extern "C" ret_type func(__VA_ARGS__) \
    147      __attribute__((alias("__interceptor_" #func), visibility("default")));
    148 #else
    149 # define WRAP(x) __interceptor_ ## x
    150 # define WRAPPER_NAME(x) "__interceptor_" #x
    151 # define INTERCEPTOR_ATTRIBUTE __attribute__((visibility("default")))
    152 # define DECLARE_WRAPPER(ret_type, func, ...) \
    153     extern "C" ret_type func(__VA_ARGS__) \
    154     __attribute__((weak, alias("__interceptor_" #func), visibility("default")));
    155 #endif
    156 
    157 #if !defined(__APPLE__)
    158 # define PTR_TO_REAL(x) real_##x
    159 # define REAL(x) __interception::PTR_TO_REAL(x)
    160 # define FUNC_TYPE(x) x##_f
    161 
    162 # define DECLARE_REAL(ret_type, func, ...) \
    163     typedef ret_type (*FUNC_TYPE(func))(__VA_ARGS__); \
    164     namespace __interception { \
    165       extern FUNC_TYPE(func) PTR_TO_REAL(func); \
    166     }
    167 #else  // __APPLE__
    168 # define REAL(x) x
    169 # define DECLARE_REAL(ret_type, func, ...) \
    170     extern "C" ret_type func(__VA_ARGS__);
    171 #endif  // __APPLE__
    172 
    173 #define DECLARE_REAL_AND_INTERCEPTOR(ret_type, func, ...) \
    174   DECLARE_REAL(ret_type, func, __VA_ARGS__) \
    175   extern "C" ret_type WRAP(func)(__VA_ARGS__);
    176 
    177 // Generally, you don't need to use DEFINE_REAL by itself, as INTERCEPTOR
    178 // macros does its job. In exceptional cases you may need to call REAL(foo)
    179 // without defining INTERCEPTOR(..., foo, ...). For example, if you override
    180 // foo with an interceptor for other function.
    181 #if !defined(__APPLE__)
    182 # define DEFINE_REAL(ret_type, func, ...) \
    183     typedef ret_type (*FUNC_TYPE(func))(__VA_ARGS__); \
    184     namespace __interception { \
    185       FUNC_TYPE(func) PTR_TO_REAL(func); \
    186     }
    187 #else
    188 # define DEFINE_REAL(ret_type, func, ...)
    189 #endif
    190 
    191 #if !defined(__APPLE__)
    192 #define INTERCEPTOR(ret_type, func, ...) \
    193   DEFINE_REAL(ret_type, func, __VA_ARGS__) \
    194   DECLARE_WRAPPER(ret_type, func, __VA_ARGS__) \
    195   extern "C" \
    196   INTERCEPTOR_ATTRIBUTE \
    197   ret_type WRAP(func)(__VA_ARGS__)
    198 
    199 // We don't need INTERCEPTOR_WITH_SUFFIX on non-Darwin for now.
    200 #define INTERCEPTOR_WITH_SUFFIX(ret_type, func, ...) \
    201   INTERCEPTOR(ret_type, func, __VA_ARGS__)
    202 
    203 #else  // __APPLE__
    204 
    205 #define INTERCEPTOR_ZZZ(suffix, ret_type, func, ...) \
    206   extern "C" ret_type func(__VA_ARGS__) suffix; \
    207   extern "C" ret_type WRAP(func)(__VA_ARGS__); \
    208   INTERPOSER(func); \
    209   extern "C" INTERCEPTOR_ATTRIBUTE ret_type WRAP(func)(__VA_ARGS__)
    210 
    211 #define INTERCEPTOR(ret_type, func, ...) \
    212   INTERCEPTOR_ZZZ(/*no symbol variants*/, ret_type, func, __VA_ARGS__)
    213 
    214 #define INTERCEPTOR_WITH_SUFFIX(ret_type, func, ...) \
    215   INTERCEPTOR_ZZZ(__DARWIN_ALIAS_C(func), ret_type, func, __VA_ARGS__)
    216 
    217 // Override |overridee| with |overrider|.
    218 #define OVERRIDE_FUNCTION(overridee, overrider) \
    219   INTERPOSER_2(overridee, WRAP(overrider))
    220 #endif
    221 
    222 #if defined(_WIN32)
    223 # define INTERCEPTOR_WINAPI(ret_type, func, ...) \
    224     typedef ret_type (__stdcall *FUNC_TYPE(func))(__VA_ARGS__); \
    225     namespace __interception { \
    226       FUNC_TYPE(func) PTR_TO_REAL(func); \
    227     } \
    228     DECLARE_WRAPPER_WINAPI(ret_type, func, __VA_ARGS__) \
    229     extern "C" \
    230     INTERCEPTOR_ATTRIBUTE \
    231     ret_type __stdcall WRAP(func)(__VA_ARGS__)
    232 #endif
    233 
    234 // ISO C++ forbids casting between pointer-to-function and pointer-to-object,
    235 // so we use casting via an integral type __interception::uptr,
    236 // assuming that system is POSIX-compliant. Using other hacks seem
    237 // challenging, as we don't even pass function type to
    238 // INTERCEPT_FUNCTION macro, only its name.
    239 namespace __interception {
    240 #if defined(_WIN64)
    241 typedef unsigned long long uptr;  // NOLINT
    242 #else
    243 typedef unsigned long uptr;  // NOLINT
    244 #endif  // _WIN64
    245 }  // namespace __interception
    246 
    247 #define INCLUDED_FROM_INTERCEPTION_LIB
    248 
    249 #if defined(__linux__) || defined(__FreeBSD__)
    250 # include "interception_linux.h"
    251 # define INTERCEPT_FUNCTION(func) INTERCEPT_FUNCTION_LINUX_OR_FREEBSD(func)
    252 # define INTERCEPT_FUNCTION_VER(func, symver) \
    253     INTERCEPT_FUNCTION_VER_LINUX_OR_FREEBSD(func, symver)
    254 #elif defined(__APPLE__)
    255 # include "interception_mac.h"
    256 # define INTERCEPT_FUNCTION(func) INTERCEPT_FUNCTION_MAC(func)
    257 # define INTERCEPT_FUNCTION_VER(func, symver) \
    258     INTERCEPT_FUNCTION_VER_MAC(func, symver)
    259 #else  // defined(_WIN32)
    260 # include "interception_win.h"
    261 # define INTERCEPT_FUNCTION(func) INTERCEPT_FUNCTION_WIN(func)
    262 # define INTERCEPT_FUNCTION_VER(func, symver) \
    263     INTERCEPT_FUNCTION_VER_WIN(func, symver)
    264 #endif
    265 
    266 #undef INCLUDED_FROM_INTERCEPTION_LIB
    267 
    268 #endif  // INTERCEPTION_H
    269