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 * \file 28 * Advanced dynamic library opening support. Most users will want to use 29 * the standard [dlopen(3)](http://man7.org/linux/man-pages/man3/dlopen.3.html) 30 * functionality in `<dlfcn.h>` instead. 31 */ 32 33 __BEGIN_DECLS 34 35 /** Bitfield definitions for `android_dlextinfo::flags`. */ 36 enum { 37 /** 38 * When set, the `reserved_addr` and `reserved_size` fields must point to an 39 * already-reserved region of address space which will be used to load the 40 * library if it fits. 41 * 42 * If the reserved region is not large enough, loading will fail. 43 */ 44 ANDROID_DLEXT_RESERVED_ADDRESS = 0x1, 45 46 /** 47 * Like `ANDROID_DLEXT_RESERVED_ADDRESS`, but if the reserved region is not large enough, 48 * the linker will choose an available address instead. 49 */ 50 ANDROID_DLEXT_RESERVED_ADDRESS_HINT = 0x2, 51 52 /** 53 * When set, write the GNU RELRO section of the mapped library to `relro_fd` 54 * after relocation has been performed, to allow it to be reused by another 55 * process loading the same library at the same address. This implies 56 * `ANDROID_DLEXT_USE_RELRO`. 57 * 58 * This is mainly useful for the system WebView implementation. 59 */ 60 ANDROID_DLEXT_WRITE_RELRO = 0x4, 61 62 /** 63 * When set, compare the GNU RELRO section of the mapped library to `relro_fd` 64 * after relocation has been performed, and replace any relocated pages that 65 * are identical with a version mapped from the file. 66 * 67 * This is mainly useful for the system WebView implementation. 68 */ 69 ANDROID_DLEXT_USE_RELRO = 0x8, 70 71 /** 72 * Use `library_fd` instead of opening the file by name. 73 * The filename parameter is still used to identify the library. 74 */ 75 ANDROID_DLEXT_USE_LIBRARY_FD = 0x10, 76 77 /** 78 * If opening a library using `library_fd` read it starting at `library_fd_offset`. 79 * This is mainly useful for loading a library stored within another file (such as uncompressed 80 * inside a ZIP archive). 81 * This flag is only valid when `ANDROID_DLEXT_USE_LIBRARY_FD` is set. 82 */ 83 ANDROID_DLEXT_USE_LIBRARY_FD_OFFSET = 0x20, 84 85 /** 86 * When set, do not use `stat(2)` to check if the library has already been loaded. 87 * 88 * This flag allows forced loading of the library in the case when for some 89 * reason multiple ELF files share the same filename (because the already-loaded 90 * library has been removed and overwritten, for example). 91 * 92 * Note that if the library has the same `DT_SONAME` as an old one and some other 93 * library has the soname in its `DT_NEEDED` list, the first one will be used to resolve any 94 * dependencies. 95 */ 96 ANDROID_DLEXT_FORCE_LOAD = 0x40, 97 98 /** 99 * When set, if the minimum `p_vaddr` of the ELF file's `PT_LOAD` segments is non-zero, 100 * the dynamic linker will load it at that address. 101 * 102 * This flag is for ART internal use only. 103 */ 104 ANDROID_DLEXT_FORCE_FIXED_VADDR = 0x80, 105 106 /** 107 * Instructs dlopen to load the library at the address specified by reserved_addr. 108 * 109 * The difference between `ANDROID_DLEXT_LOAD_AT_FIXED_ADDRESS` and 110 * `ANDROID_DLEXT_RESERVED_ADDRESS` is that for `ANDROID_DLEXT_LOAD_AT_FIXED_ADDRESS` the linker 111 * reserves memory at `reserved_addr` whereas for `ANDROID_DLEXT_RESERVED_ADDRESS` the linker 112 * relies on the caller to reserve the memory. 113 * 114 * This flag can be used with `ANDROID_DLEXT_FORCE_FIXED_VADDR`. When 115 * `ANDROID_DLEXT_FORCE_FIXED_VADDR` is set and `load_bias` is not 0 (`load_bias` is the 116 * minimum `p_vaddr` of all `PT_LOAD` segments) this flag is ignored because the linker has to 117 * pick one address over the other and this way is more convenient for ART. 118 * Note that `ANDROID_DLEXT_FORCE_FIXED_VADDR` does not generate an error when the minimum 119 * `p_vaddr` is 0. 120 * 121 * Cannot be used with `ANDROID_DLEXT_RESERVED_ADDRESS` or `ANDROID_DLEXT_RESERVED_ADDRESS_HINT`. 122 * 123 * This flag is for ART internal use only. 124 */ 125 ANDROID_DLEXT_LOAD_AT_FIXED_ADDRESS = 0x100, 126 127 /** 128 * This flag used to load library in a different namespace. The namespace is 129 * specified in `library_namespace`. 130 * 131 * This flag is for internal use only (since there is no NDK API for namespaces). 132 */ 133 ANDROID_DLEXT_USE_NAMESPACE = 0x200, 134 135 /** Mask of valid bits. */ 136 ANDROID_DLEXT_VALID_FLAG_BITS = ANDROID_DLEXT_RESERVED_ADDRESS | 137 ANDROID_DLEXT_RESERVED_ADDRESS_HINT | 138 ANDROID_DLEXT_WRITE_RELRO | 139 ANDROID_DLEXT_USE_RELRO | 140 ANDROID_DLEXT_USE_LIBRARY_FD | 141 ANDROID_DLEXT_USE_LIBRARY_FD_OFFSET | 142 ANDROID_DLEXT_FORCE_LOAD | 143 ANDROID_DLEXT_FORCE_FIXED_VADDR | 144 ANDROID_DLEXT_LOAD_AT_FIXED_ADDRESS | 145 ANDROID_DLEXT_USE_NAMESPACE, 146 }; 147 148 struct android_namespace_t; 149 150 /** Used to pass Android-specific arguments to `android_dlopen_ext`. */ 151 typedef struct { 152 /** A bitmask of `ANDROID_DLEXT_` enum values. */ 153 uint64_t flags; 154 155 /** Used by `ANDROID_DLEXT_RESERVED_ADDRESS` and `ANDROID_DLEXT_RESERVED_ADDRESS_HINT`. */ 156 void* reserved_addr; 157 /** Used by `ANDROID_DLEXT_RESERVED_ADDRESS` and `ANDROID_DLEXT_RESERVED_ADDRESS_HINT`. */ 158 size_t reserved_size; 159 160 /** Used by `ANDROID_DLEXT_WRITE_RELRO` and `ANDROID_DLEXT_USE_RELRO`. */ 161 int relro_fd; 162 163 /** Used by `ANDROID_DLEXT_USE_LIBRARY_FD`. */ 164 int library_fd; 165 /** Used by `ANDROID_DLEXT_USE_LIBRARY_FD_OFFSET` */ 166 off64_t library_fd_offset; 167 168 /** Used by `ANDROID_DLEXT_USE_NAMESPACE`. */ 169 struct android_namespace_t* library_namespace; 170 } android_dlextinfo; 171 172 /** 173 * Opens the given library. The `__filename` and `__flags` arguments are 174 * the same as for [dlopen(3)](http://man7.org/linux/man-pages/man3/dlopen.3.html), 175 * with the Android-specific flags supplied via the `flags` member of `__info`. 176 */ 177 void* android_dlopen_ext(const char* __filename, int __flags, const android_dlextinfo* __info) 178 __INTRODUCED_IN(21); 179 180 __END_DECLS 181 182 #endif 183