1 /* Macros for managing ABI-compatibility definitions using ELF symbol versions. 2 Copyright (C) 2000-2022 Free Software Foundation, Inc. 3 This file is part of the GNU C Library. 4 5 The GNU C Library is free software; you can redistribute it and/or 6 modify it under the terms of the GNU Lesser General Public 7 License as published by the Free Software Foundation; either 8 version 2.1 of the License, or (at your option) any later version. 9 10 The GNU C Library is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Lesser General Public License for more details. 14 15 You should have received a copy of the GNU Lesser General Public 16 License along with the GNU C Library; if not, see 17 <https://www.gnu.org/licenses/>. */ 18 19 #ifndef _SHLIB_COMPAT_H 20 #define _SHLIB_COMPAT_H 1 21 22 # include <abi-versions.h> 23 24 /* Obtain the definition of symbol_version_reference. */ 25 #include <libc-symver.h> 26 27 /* The file abi-versions.h (generated by scripts/abi-versions.awk) defines 28 symbols like `ABI_libm_GLIBC_2_0' for each version set in the source 29 code for each library. For a version set that is subsumed by a later 30 version set, the definition gives the subsuming set, i.e. if GLIBC_2_0 31 is subsumed by GLIBC_2_1, then ABI_libm_GLIBC_2_0 == ABI_libm_GLIBC_2_1. 32 Each version set that is to be distinctly defined in the output has an 33 unique positive integer value, increasing with newer versions. Thus, 34 evaluating two ABI_* symbols reduces to integer values that differ only 35 when the two version sets named are in fact two different ABIs we are 36 supporting. If these do not differ, then there is no need to compile in 37 extra code to support this version set where it has been superseded by a 38 newer version. */ 39 #define LIB_COMPAT(lib, introduced, obsoleted) \ 40 _LIB_COMPAT (lib, introduced, obsoleted) 41 #define _LIB_COMPAT(lib, introduced, obsoleted) \ 42 (IS_IN (lib) \ 43 && (!(ABI_##lib##_##obsoleted - 0) \ 44 || ((ABI_##lib##_##introduced - 0) < (ABI_##lib##_##obsoleted - 0)))) 45 46 #ifdef SHARED 47 48 /* Similar to LIB_COMPAT, but evaluate to 0 for static build. The 49 compatibility code should be conditionalized with e.g. 50 `#if SHLIB_COMPAT (libm, GLIBC_2_0, GLIBC_2_2)' for code introduced 51 in the GLIBC_2.0 version and obsoleted in the GLIBC_2.2 version. */ 52 53 # define SHLIB_COMPAT(lib, introduced, obsoleted) \ 54 _LIB_COMPAT (lib, introduced, obsoleted) 55 56 /* Like SHLIB_COMPAT, but it can check versions in other libraries. It is 57 not always false for !IS_IN (LIB). */ 58 #define OTHER_SHLIB_COMPAT(lib, introduced, obsoleted) \ 59 _OTHER_SHLIB_COMPAT (lib, introduced, obsoleted) 60 #define _OTHER_SHLIB_COMPAT(lib, introduced, obsoleted) \ 61 (!(ABI_##lib##_##obsoleted - 0) \ 62 || ((ABI_##lib##_##introduced - 0) < (ABI_##lib##_##obsoleted - 0))) 63 64 /* That header also defines symbols like `VERSION_libm_GLIBC_2_1' to 65 the version set name to use for e.g. symbols first introduced into 66 libm in the GLIBC_2.1 version. Definitions of symbols with explicit 67 versions should look like: 68 versioned_symbol (libm, new_foo, foo, GLIBC_2_1); 69 This will define the symbol `foo' with the appropriate default version, 70 i.e. either GLIBC_2.1 or the "earliest version" specified in 71 shlib-versions if that is newer. */ 72 73 /* versioned_symbol (LIB, LOCAL, SYMBOL, VERSION) emits a definition 74 of SYMBOL with a default (@@) VERSION appropriate for LIB. (The 75 actually emitted symbol version is adjusted according to the 76 baseline symbol version for LIB.) The address of the symbol is 77 taken from LOCAL. Properties of LOCAL are copied to the exported 78 symbol. In particular, LOCAL itself should be global. It is 79 unspecified whether SYMBOL@VERSION is associated with LOCAL, or if 80 an intermediate alias is created. If LOCAL and SYMBOL are 81 distinct, and LOCAL is also intended for export, its version should 82 be specified explicitly with versioned_symbol, too. */ 83 # define versioned_symbol(lib, local, symbol, version) \ 84 versioned_symbol_1 (lib, local, symbol, version) 85 # define versioned_symbol_1(lib, local, symbol, version) \ 86 versioned_symbol_2 (local, symbol, VERSION_##lib##_##version) 87 # define versioned_symbol_2(local, symbol, name) \ 88 default_symbol_version (local, symbol, name) 89 90 /* compat_symbol is like versioned_symbol, but emits a compatibility 91 version (with @ instead of @@). The same issue related to 92 intermediate aliases applies, so LOCAL should not be listed in the 93 Versions file, or otherwise it can be exported with an undesired 94 default symbol version. */ 95 # define compat_symbol(lib, local, symbol, version) \ 96 compat_symbol_1 (lib, local, symbol, version) 97 # define compat_symbol_1(lib, local, symbol, version) \ 98 compat_symbol_2 (local, symbol, VERSION_##lib##_##version) 99 /* See <libc-symver.h>. */ 100 # ifdef __ASSEMBLER__ 101 #define compat_symbol_2(local, symbol, name) \ 102 _set_symbol_version (local, symbol@name) 103 # else 104 # define compat_symbol_2(local, symbol, name) \ 105 compat_symbol_3 (local, symbol, name) 106 # define compat_symbol_3(local, symbol, name) \ 107 _set_symbol_version (local, #symbol "@" #name) 108 # endif 109 #else 110 111 /* Not compiling ELF shared libraries at all, so never any old versions. */ 112 # define SHLIB_COMPAT(lib, introduced, obsoleted) 0 113 # define OTHER_SHLIB_COMPAT(lib, introduced, obsoleted) 0 114 115 /* No versions to worry about, just make this the global definition. */ 116 # define versioned_symbol(lib, local, symbol, version) \ 117 weak_alias (local, symbol) 118 119 /* This should not appear outside `#if SHLIB_COMPAT (...)'. */ 120 # define compat_symbol(lib, local, symbol, version) ... 121 122 #endif 123 124 /* Use compat_symbol_reference for a reference *or* definition of a 125 specific version of a symbol. compat_symbol_reference does not 126 create intermediate aliases. Definitions are primarily used to 127 ensure tests reference the exact compat symbol required, or define 128 an interposing symbol of the right version e.g., 129 __malloc_initialize_hook in mcheck-init.c. Use compat_symbol to 130 define such a symbol within the shared libraries that are built for 131 users. */ 132 #define compat_symbol_reference(lib, local, symbol, version) \ 133 compat_symbol_reference_1 (lib, local, symbol, version) 134 #define compat_symbol_reference_1(lib, local, symbol, version) \ 135 compat_symbol_reference_2 (local, symbol, VERSION_##lib##_##version) 136 #define compat_symbol_reference_2(local, symbol, name) \ 137 symbol_version_reference (local, symbol, name) 138 139 /* Export the symbol only for shared-library compatibility. */ 140 #define libc_sunrpc_symbol(name, aliasname, version) \ 141 compat_symbol (libc, name, aliasname, version); 142 143 /* The TEST_COMPAT macro acts just like the SHLIB_COMPAT macro except 144 that it does not check IS_IN. It is used by tests that are testing 145 functionality that is only available in specific GLIBC versions. */ 146 147 # define TEST_COMPAT(lib, introduced, obsoleted) \ 148 _TEST_COMPAT (lib, introduced, obsoleted) 149 # define _TEST_COMPAT(lib, introduced, obsoleted) \ 150 (!(ABI_##lib##_##obsoleted - 0) \ 151 || ((ABI_##lib##_##introduced - 0) < (ABI_##lib##_##obsoleted - 0))) 152 153 #endif /* shlib-compat.h */ 154