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