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 <stdint.h> 32 #include <sys/cdefs.h> 33 34 __BEGIN_DECLS 35 36 /** 37 * dladdr() returns information using this structure. 38 */ 39 typedef struct { 40 /** Pathname of the shared object that contains the given address. */ 41 const char* _Nullable dli_fname; 42 /** Address at which the shared object is loaded. */ 43 void* _Nullable dli_fbase; 44 /** Name of the nearest symbol with an address lower than the given address. */ 45 const char* _Nullable dli_sname; 46 /** Exact address of the symbol named in `dli_sname`. */ 47 void* _Nullable dli_saddr; 48 } Dl_info; 49 50 /** 51 * [dlopen(3)](http://man7.org/linux/man-pages/man3/dlopen.3.html) 52 * loads the given shared library. 53 * 54 * Returns a pointer to an opaque handle for use with other <dlfcn.h> functions 55 * on success, and returns NULL on failure, in which case dlerror() can be used 56 * to retrieve the specific error. 57 */ 58 void* _Nullable dlopen(const char* _Nullable __filename, int __flag); 59 60 /** 61 * [dlclose(3)](http://man7.org/linux/man-pages/man3/dlclose.3.html) 62 * decrements the reference count for the given shared library (and 63 * any libraries brought in by that library's DT_NEEDED entries). 64 * 65 * If a library's reference count hits zero, it may be unloaded. 66 * Code that relies on this is not portable, and may not work on 67 * future versions of Android. 68 * 69 * dlclose() is dangerous because function pointers may or may not 70 * be rendered invalid, global data may or may not be rendered invalid, 71 * and memory may or may not leak. Code with global constructors is 72 * especially problematic. Instead of dlclose, prefer to leave the 73 * library open or, if cleanup is necessary, dlopen() the library in 74 * a child process which can later be killed by the parent or call 75 * exit() itself. 76 * 77 * Note also that dlclose() interacts badly with thread local variables 78 * with non-trivial destructors, with the 79 * (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]. 80 * 81 * Returns 0 on success, and returns -1 on failure, in which case 82 * dlerror() can be used to retrieve the specific error. 83 */ 84 int dlclose(void* _Nonnull __handle); 85 86 /** 87 * [dlerror(3)](http://man7.org/linux/man-pages/man3/dlerror.3.html) 88 * returns a human-readable error message describing the most recent 89 * failure from one of the <dlfcn.h> functions on the calling thread. 90 * 91 * This function also clears the error, so a second call (or a call 92 * before any failure) will return NULL. 93 * 94 * Returns a pointer to an error on success, and returns NULL if no 95 * error is pending. 96 */ 97 char* _Nullable dlerror(void); 98 99 /** 100 * [dlsym(3)](http://man7.org/linux/man-pages/man3/dlsym.3.html) 101 * returns a pointer to the symbol with the given name in the shared 102 * library represented by the given handle. The handle may have been 103 * returned from dlopen(), or can be RTLD_DEFAULT or RTLD_NEXT. 104 * 105 * Returns the address of the symbol on success, and returns NULL on failure, 106 * in which case dlerror() can be used to retrieve the specific error. 107 */ 108 void* _Nullable dlsym(void* __BIONIC_COMPLICATED_NULLNESS __handle, const char* _Nullable __symbol); 109 110 /** 111 * [dlvsym(3)](http://man7.org/linux/man-pages/man3/dlvsym.3.html) 112 * returns a pointer to the symbol with the given name and version in the shared 113 * library represented by the given handle. The handle may have been 114 * returned from dlopen(), or can be RTLD_DEFAULT or RTLD_NEXT. 115 * 116 * Returns the address of the symbol on success, and returns NULL on failure, 117 * in which case dlerror() can be used to retrieve the specific error. 118 */ 119 void* _Nullable dlvsym(void* __BIONIC_COMPLICATED_NULLNESS __handle, const char* _Nullable __symbol, const char* _Nullable __version) __INTRODUCED_IN(24); 120 121 /** 122 * [dladdr(3)](http://man7.org/linux/man-pages/man3/dladdr.3.html) 123 * returns information about the symbol at the given address. 124 * 125 * Returns non-zero on success, and returns 0 on failure. Note that unlike 126 * the other <dlfcn.h> functions, in this case dlerror() will _not_ have 127 * more information. 128 */ 129 int dladdr(const void* _Nonnull __addr, Dl_info* _Nonnull __info); 130 131 /** 132 * A dlsym()/dlvsym() handle that returns the first symbol found in any 133 * shared library using the default search order. 134 */ 135 #define RTLD_DEFAULT __BIONIC_CAST(reinterpret_cast, void*, 0) 136 137 /** 138 * A dlsym()/dlvsym() handle that returns the first symbol found in any 139 * shared library that appears _after_ the object containing the caller. 140 */ 141 #define RTLD_NEXT __BIONIC_CAST(reinterpret_cast, void*, -1L) 142 143 /** 144 * A dlopen() flag to not make symbols from this library available to later 145 * libraries. See also RTLD_GLOBAL. 146 */ 147 #define RTLD_LOCAL 0 148 149 /** Not supported on Android; Android always uses RTLD_NOW. */ 150 #define RTLD_LAZY 0x00001 151 152 /** A dlopen() flag to resolve all undefined symbols before dlopen() returns. */ 153 #define RTLD_NOW 0x00002 154 155 /** 156 * A dlopen() flag to not actually load the given library; 157 * used to test whether the library is already loaded. 158 */ 159 #define RTLD_NOLOAD 0x00004 160 161 /** 162 * A dlopen() flag to make symbols from this library available to later 163 * libraries. See also RTLD_LOCAL. 164 */ 165 #define RTLD_GLOBAL 0x00100 166 167 /** 168 * A dlopen() flag to ignore later dlclose() calls on this library. 169 */ 170 #define RTLD_NODELETE 0x01000 171 172 /* LP32 has historical ABI breakage. */ 173 #if !defined(__LP64__) 174 #undef RTLD_DEFAULT 175 #define RTLD_DEFAULT __BIONIC_CAST(reinterpret_cast, void*, 0xffffffff) 176 #undef RTLD_NEXT 177 #define RTLD_NEXT __BIONIC_CAST(reinterpret_cast, void*, 0xfffffffe) 178 #undef RTLD_NOW 179 #define RTLD_NOW 0x00000 180 #undef RTLD_GLOBAL 181 #define RTLD_GLOBAL 0x00002 182 #endif 183 184 __END_DECLS 185