libsanitizer/interception/interception.h

   1 //===-- interception.h ------------------------------------------*- C++ -*-===//
   2 //
   3 // This file is distributed under the University of Illinois Open Source
   4 // License. See LICENSE.TXT for details.
   5 //
   6 //===----------------------------------------------------------------------===//
   7 //
   8 // This file is a part of AddressSanitizer, an address sanity checker.
   9 //
  10 // Machinery for providing replacements/wrappers for system functions.
  11 //===----------------------------------------------------------------------===//
  12
  13 #ifndef INTERCEPTION_H
  14 #define INTERCEPTION_H
  15
  16 #if !defined(__linux__) && !defined(__APPLE__) && !defined(_WIN32)
  17 # error "Interception doesn't work on this operating system."
  18 #endif
  19
  20 #include "sanitizer_common/sanitizer_internal_defs.h"
  21
  22 // These typedefs should be used only in the interceptor definitions to replace
  23 // the standard system types (e.g. SSIZE_T instead of ssize_t)
  24 typedef __sanitizer::uptr SIZE_T;
  25 typedef __sanitizer::sptr SSIZE_T;
  26 typedef __sanitizer::sptr PTRDIFF_T;
  27 typedef __sanitizer::s64  INTMAX_T;
  28 // WARNING: OFF_T may be different from OS type off_t, depending on the value of
  29 // _FILE_OFFSET_BITS. This definition of OFF_T matches the ABI of system calls
  30 // like pread and mmap, as opposed to pread64 and mmap64.
  31 // Mac and Linux/x86-64 are special.
  32 #if defined(__APPLE__) || (defined(__linux__) && defined(__x86_64__))
  33 typedef __sanitizer::u64 OFF_T;
  34 #else
  35 typedef __sanitizer::uptr OFF_T;
  36 #endif
  37 typedef __sanitizer::u64  OFF64_T;
  38
  39 // How to add an interceptor:
  40 // Suppose you need to wrap/replace system function (generally, from libc):
  41 //      int foo(const char *bar, double baz);
  42 // You'll need to:
  43 //      1) define INTERCEPTOR(int, foo, const char *bar, double baz) { ... } in
  44 //         your source file.
  45 //      2) Call "INTERCEPT_FUNCTION(foo)" prior to the first call of "foo".
  46 //         INTERCEPT_FUNCTION(foo) evaluates to "true" iff the function was
  47 //         intercepted successfully.
  48 // You can access original function by calling REAL(foo)(bar, baz).
  49 // By default, REAL(foo) will be visible only inside your interceptor, and if
  50 // you want to use it in other parts of RTL, you'll need to:
  51 //      3a) add DECLARE_REAL(int, foo, const char*, double) to a
  52 //          header file.
  53 // However, if the call "INTERCEPT_FUNCTION(foo)" and definition for
  54 // INTERCEPTOR(..., foo, ...) are in different files, you'll instead need to:
  55 //      3b) add DECLARE_REAL_AND_INTERCEPTOR(int, foo, const char*, double)
  56 //          to a header file.
  57
  58 // Notes: 1. Things may not work properly if macro INTERCEPT(...) {...} or
  59 //           DECLARE_REAL(...) are located inside namespaces.
  60 //        2. On Mac you can also use: "OVERRIDE_FUNCTION(foo, zoo);" to
  61 //           effectively redirect calls from "foo" to "zoo". In this case
  62 //           you aren't required to implement
  63 //           INTERCEPTOR(int, foo, const char *bar, double baz) {...}
  64 //           but instead you'll have to add
  65 //           DEFINE_REAL(int, foo, const char *bar, double baz) in your
  66 //           source file (to define a pointer to overriden function).
  67
  68 // How it works:
  69 // To replace system functions on Linux we just need to declare functions
  70 // with same names in our library and then obtain the real function pointers
  71 // using dlsym().
  72 // There is one complication. A user may also intercept some of the functions
  73 // we intercept. To resolve this we declare our interceptors with __interceptor_
  74 // prefix, and then make actual interceptors weak aliases to __interceptor_
  75 // functions.
  76 // This is not so on Mac OS, where the two-level namespace makes
  77 // our replacement functions invisible to other libraries. This may be overcomed
  78 // using the DYLD_FORCE_FLAT_NAMESPACE, but some errors loading the shared
  79 // libraries in Chromium were noticed when doing so.
  80 // Instead we create a dylib containing a __DATA,__interpose section that
  81 // associates library functions with their wrappers. When this dylib is
  82 // preloaded before an executable using DYLD_INSERT_LIBRARIES, it routes all
  83 // the calls to interposed functions done through stubs to the wrapper
  84 // functions.
  85
  86 #if defined(__APPLE__)
  87 # define WRAP(x) wrap_##x
  88 # define WRAPPER_NAME(x) "wrap_"#x
  89 # define INTERCEPTOR_ATTRIBUTE
  90 # define DECLARE_WRAPPER(ret_type, func, ...)
  91 #elif defined(_WIN32)
  92 # if defined(_DLL)  // DLL CRT
  93 #  define WRAP(x) x
  94 #  define WRAPPER_NAME(x) #x
  95 #  define INTERCEPTOR_ATTRIBUTE
  96 # else  // Static CRT
  97 #  define WRAP(x) wrap_##x
  98 #  define WRAPPER_NAME(x) "wrap_"#x
  99 #  define INTERCEPTOR_ATTRIBUTE
 100 # endif
 101 # define DECLARE_WRAPPER(ret_type, func, ...)
 102 #else
 103 # define WRAP(x) __interceptor_ ## x
 104 # define WRAPPER_NAME(x) "__interceptor_" #x
 105 # define INTERCEPTOR_ATTRIBUTE __attribute__((visibility("default")))
 106 # define DECLARE_WRAPPER(ret_type, func, ...) \
 107     extern "C" ret_type func(__VA_ARGS__) \
 108     __attribute__((weak, alias("__interceptor_" #func), visibility("default")));
 109 #endif
 110
 111 #if !defined(__APPLE__)
 112 # define PTR_TO_REAL(x) real_##x
 113 # define REAL(x) __interception::PTR_TO_REAL(x)
 114 # define FUNC_TYPE(x) x##_f
 115
 116 # define DECLARE_REAL(ret_type, func, ...) \
 117     typedef ret_type (*FUNC_TYPE(func))(__VA_ARGS__); \
 118     namespace __interception { \
 119       extern FUNC_TYPE(func) PTR_TO_REAL(func); \
 120     }
 121 #else  // __APPLE__
 122 # define REAL(x) x
 123 # define DECLARE_REAL(ret_type, func, ...) \
 124     extern "C" ret_type func(__VA_ARGS__);
 125 #endif  // __APPLE__
 126
 127 #define DECLARE_REAL_AND_INTERCEPTOR(ret_type, func, ...) \
 128   DECLARE_REAL(ret_type, func, __VA_ARGS__) \
 129   extern "C" ret_type WRAP(func)(__VA_ARGS__);
 130
 131 // Generally, you don't need to use DEFINE_REAL by itself, as INTERCEPTOR
 132 // macros does its job. In exceptional cases you may need to call REAL(foo)
 133 // without defining INTERCEPTOR(..., foo, ...). For example, if you override
 134 // foo with an interceptor for other function.
 135 #if !defined(__APPLE__)
 136 # define DEFINE_REAL(ret_type, func, ...) \
 137     typedef ret_type (*FUNC_TYPE(func))(__VA_ARGS__); \
 138     namespace __interception { \
 139       FUNC_TYPE(func) PTR_TO_REAL(func); \
 140     }
 141 #else
 142 # define DEFINE_REAL(ret_type, func, ...)
 143 #endif
 144
 145 #define INTERCEPTOR(ret_type, func, ...) \
 146   DEFINE_REAL(ret_type, func, __VA_ARGS__) \
 147   DECLARE_WRAPPER(ret_type, func, __VA_ARGS__) \
 148   extern "C" \
 149   INTERCEPTOR_ATTRIBUTE \
 150   ret_type WRAP(func)(__VA_ARGS__)
 151
 152 #if defined(_WIN32)
 153 # define INTERCEPTOR_WINAPI(ret_type, func, ...) \
 154     typedef ret_type (__stdcall *FUNC_TYPE(func))(__VA_ARGS__); \
 155     namespace __interception { \
 156       FUNC_TYPE(func) PTR_TO_REAL(func); \
 157     } \
 158     DECLARE_WRAPPER(ret_type, func, __VA_ARGS__) \
 159     extern "C" \
 160     INTERCEPTOR_ATTRIBUTE \
 161     ret_type __stdcall WRAP(func)(__VA_ARGS__)
 162 #endif
 163
 164 // ISO C++ forbids casting between pointer-to-function and pointer-to-object,
 165 // so we use casting via an integral type __interception::uptr,
 166 // assuming that system is POSIX-compliant. Using other hacks seem
 167 // challenging, as we don't even pass function type to
 168 // INTERCEPT_FUNCTION macro, only its name.
 169 namespace __interception {
 170 #if defined(_WIN64)
 171 typedef unsigned long long uptr;  // NOLINT
 172 #else
 173 typedef unsigned long uptr;  // NOLINT
 174 #endif  // _WIN64
 175 }  // namespace __interception
 176
 177 #define INCLUDED_FROM_INTERCEPTION_LIB
 178
 179 #if defined(__linux__)
 180 # include "interception_linux.h"
 181 # define INTERCEPT_FUNCTION(func) INTERCEPT_FUNCTION_LINUX(func)
 182 #elif defined(__APPLE__)
 183 # include "interception_mac.h"
 184 # define OVERRIDE_FUNCTION(old_func, new_func) \
 185     OVERRIDE_FUNCTION_MAC(old_func, new_func)
 186 # define INTERCEPT_FUNCTION(func) INTERCEPT_FUNCTION_MAC(func)
 187 #else  // defined(_WIN32)
 188 # include "interception_win.h"
 189 # define INTERCEPT_FUNCTION(func) INTERCEPT_FUNCTION_WIN(func)
 190 #endif
 191
 192 #undef INCLUDED_FROM_INTERCEPTION_LIB
 193
 194 #endif  // INTERCEPTION_H