1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef __ANDROID_DLEXT_H__ 18 #define __ANDROID_DLEXT_H__ 19 20 #include <stdbool.h> 21 #include <stddef.h> 22 #include <stdint.h> 23 #include <sys/cdefs.h> 24 #include <sys/types.h> /* for off64_t */ 25 26 /** 27 * @addtogroup libdl Dynamic Linker 28 * @{ 29 */ 30 31 /** 32 * \file 33 * Advanced dynamic library opening support. Most users will want to use 34 * the standard [dlopen(3)](http://man7.org/linux/man-pages/man3/dlopen.3.html) 35 * functionality in `<dlfcn.h>` instead. 36 */ 37 38 __BEGIN_DECLS 39 40 /** Bitfield definitions for `android_dlextinfo::flags`. */ 41 enum { 42 /** 43 * When set, the `reserved_addr` and `reserved_size` fields must point to an 44 * already-reserved region of address space which will be used to load the 45 * library if it fits. 46 * 47 * If the reserved region is not large enough, loading will fail. 48 */ 49 ANDROID_DLEXT_RESERVED_ADDRESS = 0x1, 50 51 /** 52 * Like `ANDROID_DLEXT_RESERVED_ADDRESS`, but if the reserved region is not large enough, 53 * the linker will choose an available address instead. 54 */ 55 ANDROID_DLEXT_RESERVED_ADDRESS_HINT = 0x2, 56 57 /** 58 * When set, write the GNU RELRO section of the mapped library to `relro_fd` 59 * after relocation has been performed, to allow it to be reused by another 60 * process loading the same library at the same address. This implies 61 * `ANDROID_DLEXT_USE_RELRO`. 62 * 63 * This is mainly useful for the system WebView implementation. 64 */ 65 ANDROID_DLEXT_WRITE_RELRO = 0x4, 66 67 /** 68 * When set, compare the GNU RELRO section of the mapped library to `relro_fd` 69 * after relocation has been performed, and replace any relocated pages that 70 * are identical with a version mapped from the file. 71 * 72 * This is mainly useful for the system WebView implementation. 73 */ 74 ANDROID_DLEXT_USE_RELRO = 0x8, 75 76 /** 77 * Use `library_fd` instead of opening the file by name. 78 * The filename parameter is still used to identify the library. 79 */ 80 ANDROID_DLEXT_USE_LIBRARY_FD = 0x10, 81 82 /** 83 * If opening a library using `library_fd` read it starting at `library_fd_offset`. 84 * This is mainly useful for loading a library stored within another file (such as uncompressed 85 * inside a ZIP archive). 86 * This flag is only valid when `ANDROID_DLEXT_USE_LIBRARY_FD` is set. 87 */ 88 ANDROID_DLEXT_USE_LIBRARY_FD_OFFSET = 0x20, 89 90 /** 91 * When set, do not use `stat(2)` to check if the library has already been loaded. 92 * 93 * This flag allows forced loading of the library in the case when for some 94 * reason multiple ELF files share the same filename (because the already-loaded 95 * library has been removed and overwritten, for example). 96 * 97 * Note that if the library has the same `DT_SONAME` as an old one and some other 98 * library has the soname in its `DT_NEEDED` list, the first one will be used to resolve any 99 * dependencies. 100 */ 101 ANDROID_DLEXT_FORCE_LOAD = 0x40, 102 103 // Historically we had two other options for ART. 104 // They were last available in Android P. 105 // Reuse these bits last! 106 // ANDROID_DLEXT_FORCE_FIXED_VADDR = 0x80 107 // ANDROID_DLEXT_LOAD_AT_FIXED_ADDRESS = 0x100 108 109 /** 110 * This flag used to load library in a different namespace. The namespace is 111 * specified in `library_namespace`. 112 * 113 * This flag is for internal use only (since there is no NDK API for namespaces). 114 */ 115 ANDROID_DLEXT_USE_NAMESPACE = 0x200, 116 117 /** 118 * Instructs dlopen to apply `ANDROID_DLEXT_RESERVED_ADDRESS`, 119 * `ANDROID_DLEXT_RESERVED_ADDRESS_HINT`, `ANDROID_DLEXT_WRITE_RELRO` and 120 * `ANDROID_DLEXT_USE_RELRO` to any libraries loaded as dependencies of the 121 * main library as well. 122 * 123 * This means that if the main library depends on one or more not-already-loaded libraries, they 124 * will be loaded consecutively into the region starting at `reserved_addr`, and `reserved_size` 125 * must be large enough to contain all of the libraries. The libraries will be loaded in the 126 * deterministic order constructed from the DT_NEEDED entries, rather than the more secure random 127 * order used by default. 128 * 129 * Each library's GNU RELRO sections will be written out to `relro_fd` in the same order they were 130 * loaded. This will mean that the resulting file is dependent on which of the libraries were 131 * already loaded, as only the newly loaded libraries will be included, not any already-loaded 132 * dependencies. The caller should ensure that the set of libraries newly loaded is consistent 133 * for this to be effective. 134 * 135 * This is mainly useful for the system WebView implementation. 136 */ 137 ANDROID_DLEXT_RESERVED_ADDRESS_RECURSIVE = 0x400, 138 139 140 /** Mask of valid bits. */ 141 ANDROID_DLEXT_VALID_FLAG_BITS = ANDROID_DLEXT_RESERVED_ADDRESS | 142 ANDROID_DLEXT_RESERVED_ADDRESS_HINT | 143 ANDROID_DLEXT_WRITE_RELRO | 144 ANDROID_DLEXT_USE_RELRO | 145 ANDROID_DLEXT_USE_LIBRARY_FD | 146 ANDROID_DLEXT_USE_LIBRARY_FD_OFFSET | 147 ANDROID_DLEXT_FORCE_LOAD | 148 ANDROID_DLEXT_USE_NAMESPACE | 149 ANDROID_DLEXT_RESERVED_ADDRESS_RECURSIVE, 150 }; 151 152 struct android_namespace_t; 153 154 /** Used to pass Android-specific arguments to `android_dlopen_ext`. */ 155 typedef struct { 156 /** A bitmask of `ANDROID_DLEXT_` enum values. */ 157 uint64_t flags; 158 159 /** Used by `ANDROID_DLEXT_RESERVED_ADDRESS` and `ANDROID_DLEXT_RESERVED_ADDRESS_HINT`. */ 160 void* reserved_addr; 161 /** Used by `ANDROID_DLEXT_RESERVED_ADDRESS` and `ANDROID_DLEXT_RESERVED_ADDRESS_HINT`. */ 162 size_t reserved_size; 163 164 /** Used by `ANDROID_DLEXT_WRITE_RELRO` and `ANDROID_DLEXT_USE_RELRO`. */ 165 int relro_fd; 166 167 /** Used by `ANDROID_DLEXT_USE_LIBRARY_FD`. */ 168 int library_fd; 169 /** Used by `ANDROID_DLEXT_USE_LIBRARY_FD_OFFSET` */ 170 off64_t library_fd_offset; 171 172 /** Used by `ANDROID_DLEXT_USE_NAMESPACE`. */ 173 struct android_namespace_t* library_namespace; 174 } android_dlextinfo; 175 176 /** 177 * Opens the given library. The `__filename` and `__flags` arguments are 178 * the same as for [dlopen(3)](http://man7.org/linux/man-pages/man3/dlopen.3.html), 179 * with the Android-specific flags supplied via the `flags` member of `__info`. 180 * 181 * Available since API level 21. 182 */ 183 void* android_dlopen_ext(const char* __filename, int __flags, const android_dlextinfo* __info) 184 __INTRODUCED_IN(21); 185 186 __END_DECLS 187 188 /** @} */ 189 190 #endif 191