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 67 * [Android changes for NDK developers](https://android.googlesource.com/platform/bionic/+/main/android-changes-for-ndk-developers.md) 68 * which should cover all dynamic linker behavioral changes relevant to app development. 69 * It also explains how to debug issues with shared libraries on Android 70 * using the `debug.ld.app.*` system properties. 71 * 72 * One Android-specific extension is particularly noteworthy. 73 * The "my_zip_file.zip!/libs/libstuff.so" syntax to load a library 74 * directly from an arbitrary zip file, including but not limited to your apk 75 * (where this is how `extractNativeLibs=false` is implemented). 76 * Related to that, until API level 36 PackageManager is fussy about what 77 * files `extractNativeLibs` will actually extract. 78 * To be compatible with all API levels, 79 * always give files that need to be extracted a "lib" prefix and ".so" suffix, 80 * or avoid using `extractNativeLibs`. 81 * 82 * See also android_dlopen_ext(). 83 * 84 * Returns a pointer to an opaque handle for use with other <dlfcn.h> functions 85 * on success, and returns NULL on failure, in which case dlerror() can be used 86 * to retrieve the specific error. 87 */ 88 void* _Nullable dlopen(const char* _Nullable __filename, int __flag); 89 90 /** 91 * [dlclose(3)](https://man7.org/linux/man-pages/man3/dlclose.3.html) 92 * decrements the reference count for the given shared library (and 93 * any libraries brought in by that library's DT_NEEDED entries). 94 * 95 * If a library's reference count hits zero, it may be unloaded. 96 * Code that relies on this is not portable, and may not work on 97 * future versions of Android. 98 * 99 * dlclose() is dangerous because function pointers may or may not 100 * be rendered invalid, global data may or may not be rendered invalid, 101 * and memory may or may not leak. Code with global constructors is 102 * especially problematic. Instead of dlclose, prefer to leave the 103 * library open or, if cleanup is necessary, dlopen() the library in 104 * a child process which can later be killed by the parent or call 105 * exit() itself. 106 * 107 * Note also that dlclose() interacts badly with thread local variables 108 * with non-trivial destructors, with the 109 * (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]. 110 * 111 * Returns 0 on success, and returns -1 on failure, in which case 112 * dlerror() can be used to retrieve the specific error. 113 */ 114 int dlclose(void* _Nonnull __handle); 115 116 /** 117 * [dlerror(3)](https://man7.org/linux/man-pages/man3/dlerror.3.html) 118 * returns a human-readable error message describing the most recent 119 * failure from one of the <dlfcn.h> functions on the calling thread. 120 * 121 * This function also clears the error, so a second call (or a call 122 * before any failure) will return NULL. 123 * 124 * Returns a pointer to an error on success, and returns NULL if no 125 * error is pending. 126 */ 127 char* _Nullable dlerror(void); 128 129 /** 130 * [dlsym(3)](https://man7.org/linux/man-pages/man3/dlsym.3.html) 131 * returns a pointer to the symbol with the given name in the shared 132 * library represented by the given handle. The handle may have been 133 * returned from dlopen(), or can be RTLD_DEFAULT or RTLD_NEXT. 134 * 135 * Returns the address of the symbol on success, and returns NULL on failure, 136 * in which case dlerror() can be used to retrieve the specific error. 137 */ 138 void* _Nullable dlsym(void* __BIONIC_COMPLICATED_NULLNESS __handle, const char* _Nullable __symbol); 139 140 /** 141 * [dlvsym(3)](https://man7.org/linux/man-pages/man3/dlvsym.3.html) 142 * returns a pointer to the symbol with the given name and version in the shared 143 * library represented by the given handle. The handle may have been 144 * returned from dlopen(), or can be RTLD_DEFAULT or RTLD_NEXT. 145 * 146 * Returns the address of the symbol on success, and returns NULL on failure, 147 * in which case dlerror() can be used to retrieve the specific error. 148 */ 149 150 #if __BIONIC_AVAILABILITY_GUARD(24) 151 void* _Nullable dlvsym(void* __BIONIC_COMPLICATED_NULLNESS __handle, const char* _Nullable __symbol, const char* _Nullable __version) __INTRODUCED_IN(24); 152 #endif /* __BIONIC_AVAILABILITY_GUARD(24) */ 153 154 155 /** 156 * [dladdr(3)](https://man7.org/linux/man-pages/man3/dladdr.3.html) 157 * returns information about the symbol at the given address. 158 * 159 * Returns non-zero on success, and returns 0 on failure. Note that unlike 160 * the other <dlfcn.h> functions, in this case dlerror() will _not_ have 161 * more information. 162 */ 163 int dladdr(const void* _Nonnull __addr, Dl_info* _Nonnull __info); 164 165 /** 166 * A dlsym()/dlvsym() handle that returns the first symbol found in any 167 * shared library using the default search order. 168 */ 169 #define RTLD_DEFAULT __BIONIC_CAST(reinterpret_cast, void*, 0) 170 171 /** 172 * A dlsym()/dlvsym() handle that returns the first symbol found in any 173 * shared library that appears _after_ the object containing the caller. 174 */ 175 #define RTLD_NEXT __BIONIC_CAST(reinterpret_cast, void*, -1L) 176 177 /** 178 * A dlopen() flag to not make symbols from this library available to later 179 * libraries. See also RTLD_GLOBAL. 180 */ 181 #define RTLD_LOCAL 0 182 183 /** 184 * Not supported on Android. Android always uses RTLD_NOW for security reasons. 185 * Resolving all undefined symbols before dlopen() returns means that RELRO 186 * protections can be applied to the PLT before dlopen() returns. 187 */ 188 #define RTLD_LAZY 0x00001 189 190 /** A dlopen() flag to resolve all undefined symbols before dlopen() returns. */ 191 #define RTLD_NOW 0x00002 192 193 /** 194 * A dlopen() flag to not actually load the given library; 195 * used to test whether the library is already loaded. 196 */ 197 #define RTLD_NOLOAD 0x00004 198 199 /** 200 * A dlopen() flag to make symbols from this library available to later 201 * libraries. See also RTLD_LOCAL. 202 */ 203 #define RTLD_GLOBAL 0x00100 204 205 /** 206 * A dlopen() flag to ignore later dlclose() calls on this library. 207 */ 208 #define RTLD_NODELETE 0x01000 209 210 /* LP32 has historical ABI breakage. */ 211 #if !defined(__LP64__) 212 #undef RTLD_DEFAULT 213 #define RTLD_DEFAULT __BIONIC_CAST(reinterpret_cast, void*, 0xffffffff) 214 #undef RTLD_NEXT 215 #define RTLD_NEXT __BIONIC_CAST(reinterpret_cast, void*, 0xfffffffe) 216 #undef RTLD_NOW 217 #define RTLD_NOW 0x00000 218 #undef RTLD_GLOBAL 219 #define RTLD_GLOBAL 0x00002 220 #endif 221 222 __END_DECLS 223 224 /** @} */ 225