1 /* 2 * Copyright (C) 2008 The Android Open Source Project 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * * Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * * Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in 12 * the documentation and/or other materials provided with the 13 * distribution. 14 * 15 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 16 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 17 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 18 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 19 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 21 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 22 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 23 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 25 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26 * SUCH DAMAGE. 27 */ 28 29 #pragma once 30 31 #include <sys/cdefs.h> 32 33 #include <stdint.h> 34 35 /** 36 * @addtogroup libdl Dynamic Linker 37 * @{ 38 */ 39 40 /** 41 * \file 42 * Standard dynamic library support. 43 * See also the Android-specific functionality in `<android/dlext.h>`. 44 */ 45 46 __BEGIN_DECLS 47 48 /** 49 * dladdr() returns information using this structure. 50 */ 51 typedef struct { 52 /** Pathname of the shared object that contains the given address. */ 53 const char* _Nullable dli_fname; 54 /** Address at which the shared object is loaded. */ 55 void* _Nullable dli_fbase; 56 /** Name of the nearest symbol with an address lower than the given address. */ 57 const char* _Nullable dli_sname; 58 /** Exact address of the symbol named in `dli_sname`. */ 59 void* _Nullable dli_saddr; 60 } Dl_info; 61 62 /** 63 * [dlopen(3)](https://man7.org/linux/man-pages/man3/dlopen.3.html) 64 * loads the given shared library. 65 * 66 * See also android_dlopen_ext(). 67 * 68 * Returns a pointer to an opaque handle for use with other <dlfcn.h> functions 69 * on success, and returns NULL on failure, in which case dlerror() can be used 70 * to retrieve the specific error. 71 */ 72 void* _Nullable dlopen(const char* _Nullable __filename, int __flag); 73 74 /** 75 * [dlclose(3)](https://man7.org/linux/man-pages/man3/dlclose.3.html) 76 * decrements the reference count for the given shared library (and 77 * any libraries brought in by that library's DT_NEEDED entries). 78 * 79 * If a library's reference count hits zero, it may be unloaded. 80 * Code that relies on this is not portable, and may not work on 81 * future versions of Android. 82 * 83 * dlclose() is dangerous because function pointers may or may not 84 * be rendered invalid, global data may or may not be rendered invalid, 85 * and memory may or may not leak. Code with global constructors is 86 * especially problematic. Instead of dlclose, prefer to leave the 87 * library open or, if cleanup is necessary, dlopen() the library in 88 * a child process which can later be killed by the parent or call 89 * exit() itself. 90 * 91 * Note also that dlclose() interacts badly with thread local variables 92 * with non-trivial destructors, with the 93 * (exact behavior varying by API level)[https://android.googlesource.com/platform/bionic/+/main/android-changes-for-ndk-developers.md#dlclose-interacts-badly-with-thread-local-variables-with-non_trivial-destructors]. 94 * 95 * Returns 0 on success, and returns -1 on failure, in which case 96 * dlerror() can be used to retrieve the specific error. 97 */ 98 int dlclose(void* _Nonnull __handle); 99 100 /** 101 * [dlerror(3)](https://man7.org/linux/man-pages/man3/dlerror.3.html) 102 * returns a human-readable error message describing the most recent 103 * failure from one of the <dlfcn.h> functions on the calling thread. 104 * 105 * This function also clears the error, so a second call (or a call 106 * before any failure) will return NULL. 107 * 108 * Returns a pointer to an error on success, and returns NULL if no 109 * error is pending. 110 */ 111 char* _Nullable dlerror(void); 112 113 /** 114 * [dlsym(3)](https://man7.org/linux/man-pages/man3/dlsym.3.html) 115 * returns a pointer to the symbol with the given name in the shared 116 * library represented by the given handle. The handle may have been 117 * returned from dlopen(), or can be RTLD_DEFAULT or RTLD_NEXT. 118 * 119 * Returns the address of the symbol on success, and returns NULL on failure, 120 * in which case dlerror() can be used to retrieve the specific error. 121 */ 122 void* _Nullable dlsym(void* __BIONIC_COMPLICATED_NULLNESS __handle, const char* _Nullable __symbol); 123 124 /** 125 * [dlvsym(3)](https://man7.org/linux/man-pages/man3/dlvsym.3.html) 126 * returns a pointer to the symbol with the given name and version in the shared 127 * library represented by the given handle. The handle may have been 128 * returned from dlopen(), or can be RTLD_DEFAULT or RTLD_NEXT. 129 * 130 * Returns the address of the symbol on success, and returns NULL on failure, 131 * in which case dlerror() can be used to retrieve the specific error. 132 */ 133 134 #if __BIONIC_AVAILABILITY_GUARD(24) 135 void* _Nullable dlvsym(void* __BIONIC_COMPLICATED_NULLNESS __handle, const char* _Nullable __symbol, const char* _Nullable __version) __INTRODUCED_IN(24); 136 #endif /* __BIONIC_AVAILABILITY_GUARD(24) */ 137 138 139 /** 140 * [dladdr(3)](https://man7.org/linux/man-pages/man3/dladdr.3.html) 141 * returns information about the symbol at the given address. 142 * 143 * Returns non-zero on success, and returns 0 on failure. Note that unlike 144 * the other <dlfcn.h> functions, in this case dlerror() will _not_ have 145 * more information. 146 */ 147 int dladdr(const void* _Nonnull __addr, Dl_info* _Nonnull __info); 148 149 /** 150 * A dlsym()/dlvsym() handle that returns the first symbol found in any 151 * shared library using the default search order. 152 */ 153 #define RTLD_DEFAULT __BIONIC_CAST(reinterpret_cast, void*, 0) 154 155 /** 156 * A dlsym()/dlvsym() handle that returns the first symbol found in any 157 * shared library that appears _after_ the object containing the caller. 158 */ 159 #define RTLD_NEXT __BIONIC_CAST(reinterpret_cast, void*, -1L) 160 161 /** 162 * A dlopen() flag to not make symbols from this library available to later 163 * libraries. See also RTLD_GLOBAL. 164 */ 165 #define RTLD_LOCAL 0 166 167 /** 168 * Not supported on Android. Android always uses RTLD_NOW for security reasons. 169 * Resolving all undefined symbols before dlopen() returns means that RELRO 170 * protections can be applied to the PLT before dlopen() returns. 171 */ 172 #define RTLD_LAZY 0x00001 173 174 /** A dlopen() flag to resolve all undefined symbols before dlopen() returns. */ 175 #define RTLD_NOW 0x00002 176 177 /** 178 * A dlopen() flag to not actually load the given library; 179 * used to test whether the library is already loaded. 180 */ 181 #define RTLD_NOLOAD 0x00004 182 183 /** 184 * A dlopen() flag to make symbols from this library available to later 185 * libraries. See also RTLD_LOCAL. 186 */ 187 #define RTLD_GLOBAL 0x00100 188 189 /** 190 * A dlopen() flag to ignore later dlclose() calls on this library. 191 */ 192 #define RTLD_NODELETE 0x01000 193 194 /* LP32 has historical ABI breakage. */ 195 #if !defined(__LP64__) 196 #undef RTLD_DEFAULT 197 #define RTLD_DEFAULT __BIONIC_CAST(reinterpret_cast, void*, 0xffffffff) 198 #undef RTLD_NEXT 199 #define RTLD_NEXT __BIONIC_CAST(reinterpret_cast, void*, 0xfffffffe) 200 #undef RTLD_NOW 201 #define RTLD_NOW 0x00000 202 #undef RTLD_GLOBAL 203 #define RTLD_GLOBAL 0x00002 204 #endif 205 206 __END_DECLS 207 208 /** @} */ 209