xref: /freebsd/contrib/llvm-project/libcxx/src/include/overridable_function.h (revision 5b56413d04e608379c9a306373554a8e4d321bc0)
1 // -*- C++ -*-
2 //===----------------------------------------------------------------------===//
3 //
4 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
5 // See https://llvm.org/LICENSE.txt for license information.
6 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //
8 //===----------------------------------------------------------------------===//
9 
10 #ifndef _LIBCPP_SRC_INCLUDE_OVERRIDABLE_FUNCTION_H
11 #define _LIBCPP_SRC_INCLUDE_OVERRIDABLE_FUNCTION_H
12 
13 #include <__config>
14 #include <cstdint>
15 
16 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
17 #  pragma GCC system_header
18 #endif
19 
20 //
21 // This file provides the std::__is_function_overridden utility, which allows checking
22 // whether an overridable function (typically a weak symbol) like `operator new`
23 // has been overridden by a user or not.
24 //
25 // This is a low-level utility which does not work on all platforms, since it needs
26 // to make assumptions about the object file format in use. Furthermore, it requires
27 // the "base definition" of the function (the one we want to check whether it has been
28 // overridden) to be annotated with the _LIBCPP_MAKE_OVERRIDABLE_FUNCTION_DETECTABLE macro.
29 //
30 // This currently works with Mach-O files (used on Darwin) and with ELF files (used on Linux
31 // and others). On platforms where we know how to implement this detection, the macro
32 // _LIBCPP_CAN_DETECT_OVERRIDDEN_FUNCTION is defined to 1, and it is defined to 0 on
33 // other platforms. The _LIBCPP_MAKE_OVERRIDABLE_FUNCTION_DETECTABLE macro is defined to
34 // nothing on unsupported platforms so that it can be used to decorate functions regardless
35 // of whether detection is actually supported.
36 //
37 // How does this work?
38 // -------------------
39 //
40 // Let's say we want to check whether a weak function `f` has been overridden by the user.
41 // The general mechanism works by placing `f`'s definition (in the libc++ built library)
42 // inside a special section, which we do using the `__section__` attribute via the
43 // _LIBCPP_MAKE_OVERRIDABLE_FUNCTION_DETECTABLE macro.
44 //
45 // Then, when comes the time to check whether the function has been overridden, we take
46 // the address of the function and we check whether it falls inside the special function
47 // we created. This can be done by finding pointers to the start and the end of the section
48 // (which is done differently for ELF and Mach-O), and then checking whether `f` falls
49 // within those bounds. If it falls within those bounds, then `f` is still inside the
50 // special section and so it is the version we defined in the libc++ built library, i.e.
51 // it was not overridden. Otherwise, it was overridden by the user because it falls
52 // outside of the section.
53 //
54 // Important note
55 // --------------
56 //
57 // This mechanism should never be used outside of the libc++ built library. In particular,
58 // attempting to use this within the libc++ headers will not work at all because we don't
59 // want to be defining special sections inside user's executables which use our headers.
60 // This is provided inside libc++'s include tree solely to make it easier to share with
61 // libc++abi, which needs the same mechanism.
62 //
63 
64 #if defined(_LIBCPP_OBJECT_FORMAT_MACHO)
65 
66 #  define _LIBCPP_CAN_DETECT_OVERRIDDEN_FUNCTION 1
67 #  define _LIBCPP_MAKE_OVERRIDABLE_FUNCTION_DETECTABLE                                                                 \
68     __attribute__((__section__("__TEXT,__lcxx_override,regular,pure_instructions")))
69 
70 _LIBCPP_BEGIN_NAMESPACE_STD
71 template <class _Ret, class... _Args>
72 _LIBCPP_HIDE_FROM_ABI bool __is_function_overridden(_Ret (*__fptr)(_Args...)) noexcept {
73   // Declare two dummy bytes and give them these special `__asm` values. These values are
74   // defined by the linker, which means that referring to `&__lcxx_override_start` will
75   // effectively refer to the address where the section starts (and same for the end).
76   extern char __lcxx_override_start __asm("section$start$__TEXT$__lcxx_override");
77   extern char __lcxx_override_end __asm("section$end$__TEXT$__lcxx_override");
78 
79   // Now get a uintptr_t out of these locations, and out of the function pointer.
80   uintptr_t __start = reinterpret_cast<uintptr_t>(&__lcxx_override_start);
81   uintptr_t __end   = reinterpret_cast<uintptr_t>(&__lcxx_override_end);
82   uintptr_t __ptr   = reinterpret_cast<uintptr_t>(__fptr);
83 
84   // Finally, the function was overridden if it falls outside of the section's bounds.
85   return __ptr < __start || __ptr > __end;
86 }
87 _LIBCPP_END_NAMESPACE_STD
88 
89 #elif defined(_LIBCPP_OBJECT_FORMAT_ELF)
90 
91 #  define _LIBCPP_CAN_DETECT_OVERRIDDEN_FUNCTION 1
92 #  define _LIBCPP_MAKE_OVERRIDABLE_FUNCTION_DETECTABLE __attribute__((__section__("__lcxx_override")))
93 
94 // This is very similar to what we do for Mach-O above. The ELF linker will implicitly define
95 // variables with those names corresponding to the start and the end of the section.
96 //
97 // See https://stackoverflow.com/questions/16552710/how-do-you-get-the-start-and-end-addresses-of-a-custom-elf-section
98 extern char __start___lcxx_override;
99 extern char __stop___lcxx_override;
100 
101 _LIBCPP_BEGIN_NAMESPACE_STD
102 template <class _Ret, class... _Args>
103 _LIBCPP_HIDE_FROM_ABI bool __is_function_overridden(_Ret (*__fptr)(_Args...)) noexcept {
104   uintptr_t __start = reinterpret_cast<uintptr_t>(&__start___lcxx_override);
105   uintptr_t __end   = reinterpret_cast<uintptr_t>(&__stop___lcxx_override);
106   uintptr_t __ptr   = reinterpret_cast<uintptr_t>(__fptr);
107 
108   return __ptr < __start || __ptr > __end;
109 }
110 _LIBCPP_END_NAMESPACE_STD
111 
112 #else
113 
114 #  define _LIBCPP_CAN_DETECT_OVERRIDDEN_FUNCTION 0
115 #  define _LIBCPP_MAKE_OVERRIDABLE_FUNCTION_DETECTABLE /* nothing */
116 
117 #endif
118 
119 #endif // _LIBCPP_SRC_INCLUDE_OVERRIDABLE_FUNCTION_H
120