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 __has_feature(ptrauth_calls)
17# include <ptrauth.h>
18#endif
19
20#if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
21# pragma GCC system_header
22#endif
23
24//
25// This file provides the std::__is_function_overridden utility, which allows checking
26// whether an overridable function (typically a weak symbol) like `operator new`
27// has been overridden by a user or not.
28//
29// This is a low-level utility which does not work on all platforms, since it needs
30// to make assumptions about the object file format in use. Furthermore, it requires
31// the "base definition" of the function (the one we want to check whether it has been
32// overridden) to be defined using the _LIBCPP_OVERRIDABLE_FUNCTION macro.
33//
34// This currently works with Mach-O files (used on Darwin) and with ELF files (used on Linux
35// and others). On platforms where we know how to implement this detection, the macro
36// _LIBCPP_CAN_DETECT_OVERRIDDEN_FUNCTION is defined to 1, and it is defined to 0 on
37// other platforms. The _LIBCPP_OVERRIDABLE_FUNCTION macro is defined to perform a normal
38// function definition on unsupported platforms so that it can be used to define functions
39// regardless of whether detection is actually supported.
40//
41// How does this work?
42// -------------------
43//
44// Let's say we want to check whether a weak function `f` has been overridden by the user.
45// The general mechanism works by placing `f`'s definition (in the libc++ built library)
46// inside a special section, which we do using the `__section__` attribute via the
47// _LIBCPP_OVERRIDABLE_FUNCTION macro.
48//
49// Then, when comes the time to check whether the function has been overridden, we take
50// the address of the function and we check whether it falls inside the special function
51// we created. This can be done by finding pointers to the start and the end of the section
52// (which is done differently for ELF and Mach-O), and then checking whether `f` falls
53// within those bounds. If it falls within those bounds, then `f` is still inside the
54// special section and so it is the version we defined in the libc++ built library, i.e.
55// it was not overridden. Otherwise, it was overridden by the user because it falls
56// outside of the section.
57//
58// Important note
59// --------------
60//
61// This mechanism should never be used outside of the libc++ built library. In particular,
62// attempting to use this within the libc++ headers will not work at all because we don't
63// want to be defining special sections inside user's executables which use our headers.
64//
65
66#if defined(_LIBCPP_OBJECT_FORMAT_MACHO)
67
68# define _LIBCPP_CAN_DETECT_OVERRIDDEN_FUNCTION 1
69# define _LIBCPP_OVERRIDABLE_FUNCTION(type, name, arglist) \
70 __attribute__((__section__("__TEXT,__lcxx_override,regular,pure_instructions"))) _LIBCPP_WEAK type name arglist
71
72_LIBCPP_BEGIN_NAMESPACE_STD
73template <typename T, T* _Func>
74_LIBCPP_HIDE_FROM_ABI inline bool __is_function_overridden() noexcept {
75 // Declare two dummy bytes and give them these special `__asm` values. These values are
76 // defined by the linker, which means that referring to `&__lcxx_override_start` will
77 // effectively refer to the address where the section starts (and same for the end).
78 extern char __lcxx_override_start __asm("section$start$__TEXT$__lcxx_override");
79 extern char __lcxx_override_end __asm("section$end$__TEXT$__lcxx_override");
80
81 // Now get a uintptr_t out of these locations, and out of the function pointer.
82 uintptr_t __start = reinterpret_cast<uintptr_t>(&__lcxx_override_start);
83 uintptr_t __end = reinterpret_cast<uintptr_t>(&__lcxx_override_end);
84 uintptr_t __ptr = reinterpret_cast<uintptr_t>(_Func);
85
86# if __has_feature(ptrauth_calls)
87 // We must pass a void* to ptrauth_strip since it only accepts a pointer type. Also, in particular,
88 // we must NOT pass a function pointer, otherwise we will strip the function pointer, and then attempt
89 // to authenticate and re-sign it when casting it to a uintptr_t again, which will fail because we just
90 // stripped the function pointer. See rdar://122927845.
91 __ptr = reinterpret_cast<uintptr_t>(ptrauth_strip(reinterpret_cast<void*>(__ptr), ptrauth_key_function_pointer));
92# endif
93
94 // Finally, the function was overridden if it falls outside of the section's bounds.
95 return __ptr < __start || __ptr > __end;
96}
97_LIBCPP_END_NAMESPACE_STD
98
99// The NVPTX linker cannot create '__start/__stop' sections.
100#elif defined(_LIBCPP_OBJECT_FORMAT_ELF) && !defined(__NVPTX__)
101
102# define _LIBCPP_CAN_DETECT_OVERRIDDEN_FUNCTION 1
103# define _LIBCPP_OVERRIDABLE_FUNCTION(type, name, arglist) \
104 __attribute__((__section__("__lcxx_override"))) _LIBCPP_WEAK type name arglist
105
106// This is very similar to what we do for Mach-O above. The ELF linker will implicitly define
107// variables with those names corresponding to the start and the end of the section.
108//
109// See https://stackoverflow.com/questions/16552710/how-do-you-get-the-start-and-end-addresses-of-a-custom-elf-section
110extern char __start___lcxx_override;
111extern char __stop___lcxx_override;
112
113_LIBCPP_BEGIN_NAMESPACE_STD
114template <typename T, T* _Func>
115_LIBCPP_HIDE_FROM_ABI inline bool __is_function_overridden() noexcept {
116 uintptr_t __start = reinterpret_cast<uintptr_t>(&__start___lcxx_override);
117 uintptr_t __end = reinterpret_cast<uintptr_t>(&__stop___lcxx_override);
118 uintptr_t __ptr = reinterpret_cast<uintptr_t>(_Func);
119
120# if __has_feature(ptrauth_calls)
121 // We must pass a void* to ptrauth_strip since it only accepts a pointer type. See full explanation above.
122 __ptr = reinterpret_cast<uintptr_t>(ptrauth_strip(reinterpret_cast<void*>(__ptr), ptrauth_key_function_pointer));
123# endif
124
125 return __ptr < __start || __ptr > __end;
126}
127_LIBCPP_END_NAMESPACE_STD
128
129#else
130
131# define _LIBCPP_CAN_DETECT_OVERRIDDEN_FUNCTION 0
132# define _LIBCPP_OVERRIDABLE_FUNCTION(type, name, arglist) _LIBCPP_WEAK type name arglist
133
134#endif
135
136#endif // _LIBCPP_SRC_INCLUDE_OVERRIDABLE_FUNCTION_H
137