1 /* User functions for run-time dynamic loading. 2 Copyright (C) 1995-2021 Free Software Foundation, Inc. 3 This file is part of the GNU C Library. 4 5 The GNU C Library is free software; you can redistribute it and/or 6 modify it under the terms of the GNU Lesser General Public 7 License as published by the Free Software Foundation; either 8 version 2.1 of the License, or (at your option) any later version. 9 10 The GNU C Library is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Lesser General Public License for more details. 14 15 You should have received a copy of the GNU Lesser General Public 16 License along with the GNU C Library; if not, see 17 <https://www.gnu.org/licenses/>. */ 18 19 #ifndef _DLFCN_H 20 #define _DLFCN_H 1 21 22 #include <features.h> 23 #define __need_size_t 24 #include <stddef.h> 25 26 /* Collect various system dependent definitions and declarations. */ 27 #include <bits/dlfcn.h> 28 29 30 #ifdef __USE_GNU 31 #include <bits/dl_find_object.h> 32 33 /* If the first argument of `dlsym' or `dlvsym' is set to RTLD_NEXT 34 the run-time address of the symbol called NAME in the next shared 35 object is returned. The "next" relation is defined by the order 36 the shared objects were loaded. */ 37 # define RTLD_NEXT ((void *) -1l) 38 39 /* If the first argument to `dlsym' or `dlvsym' is set to RTLD_DEFAULT 40 the run-time address of the symbol called NAME in the global scope 41 is returned. */ 42 # define RTLD_DEFAULT ((void *) 0) 43 44 45 /* Type for namespace indices. */ 46 typedef long int Lmid_t; 47 48 /* Special namespace ID values. */ 49 # define LM_ID_BASE 0 /* Initial namespace. */ 50 # define LM_ID_NEWLM -1 /* For dlmopen: request new namespace. */ 51 #endif 52 53 54 __BEGIN_DECLS 55 56 /* Open the shared object FILE and map it in; return a handle that can be 57 passed to `dlsym' to get symbol values from it. */ 58 extern void *dlopen (const char *__file, int __mode) __THROWNL; 59 60 /* Unmap and close a shared object opened by `dlopen'. 61 The handle cannot be used again after calling `dlclose'. */ 62 extern int dlclose (void *__handle) __THROWNL __nonnull ((1)); 63 64 /* Find the run-time address in the shared object HANDLE refers to 65 of the symbol called NAME. */ 66 extern void *dlsym (void *__restrict __handle, 67 const char *__restrict __name) __THROW __nonnull ((2)); 68 69 #ifdef __USE_GNU 70 /* Like `dlopen', but request object to be allocated in a new namespace. */ 71 extern void *dlmopen (Lmid_t __nsid, const char *__file, int __mode) __THROWNL; 72 73 /* Find the run-time address in the shared object HANDLE refers to 74 of the symbol called NAME with VERSION. */ 75 extern void *dlvsym (void *__restrict __handle, 76 const char *__restrict __name, 77 const char *__restrict __version) 78 __THROW __nonnull ((2, 3)); 79 #endif 80 81 /* When any of the above functions fails, call this function 82 to return a string describing the error. Each call resets 83 the error string so that a following call returns null. */ 84 extern char *dlerror (void) __THROW; 85 86 87 #ifdef __USE_GNU 88 /* Structure containing information about object searched using 89 `dladdr'. */ 90 typedef struct 91 { 92 const char *dli_fname; /* File name of defining object. */ 93 void *dli_fbase; /* Load address of that object. */ 94 const char *dli_sname; /* Name of nearest symbol. */ 95 void *dli_saddr; /* Exact value of nearest symbol. */ 96 } Dl_info; 97 98 /* Fill in *INFO with the following information about ADDRESS. 99 Returns 0 iff no shared object's segments contain that address. */ 100 extern int dladdr (const void *__address, Dl_info *__info) 101 __THROW __nonnull ((2)); 102 103 /* Same as `dladdr', but additionally sets *EXTRA_INFO according to FLAGS. */ 104 extern int dladdr1 (const void *__address, Dl_info *__info, 105 void **__extra_info, int __flags) __THROW __nonnull ((2)); 106 107 /* These are the possible values for the FLAGS argument to `dladdr1'. 108 This indicates what extra information is stored at *EXTRA_INFO. 109 It may also be zero, in which case the EXTRA_INFO argument is not used. */ 110 enum 111 { 112 /* Matching symbol table entry (const ElfNN_Sym *). */ 113 RTLD_DL_SYMENT = 1, 114 115 /* The object containing the address (struct link_map *). */ 116 RTLD_DL_LINKMAP = 2 117 }; 118 119 120 /* Get information about the shared object HANDLE refers to. 121 REQUEST is from among the values below, and determines the use of ARG. 122 123 On success, returns zero. On failure, returns -1 and records an error 124 message to be fetched with `dlerror'. */ 125 extern int dlinfo (void *__restrict __handle, 126 int __request, void *__restrict __arg) 127 __THROW __nonnull ((1, 3)); 128 129 /* These are the possible values for the REQUEST argument to `dlinfo'. */ 130 enum 131 { 132 /* Treat ARG as `lmid_t *'; store namespace ID for HANDLE there. */ 133 RTLD_DI_LMID = 1, 134 135 /* Treat ARG as `struct link_map **'; 136 store the `struct link_map *' for HANDLE there. */ 137 RTLD_DI_LINKMAP = 2, 138 139 RTLD_DI_CONFIGADDR = 3, /* Unsupported, defined by Solaris. */ 140 141 /* Treat ARG as `Dl_serinfo *' (see below), and fill in to describe the 142 directories that will be searched for dependencies of this object. 143 RTLD_DI_SERINFOSIZE fills in just the `dls_cnt' and `dls_size' 144 entries to indicate the size of the buffer that must be passed to 145 RTLD_DI_SERINFO to fill in the full information. */ 146 RTLD_DI_SERINFO = 4, 147 RTLD_DI_SERINFOSIZE = 5, 148 149 /* Treat ARG as `char *', and store there the directory name used to 150 expand $ORIGIN in this shared object's dependency file names. */ 151 RTLD_DI_ORIGIN = 6, 152 153 RTLD_DI_PROFILENAME = 7, /* Unsupported, defined by Solaris. */ 154 RTLD_DI_PROFILEOUT = 8, /* Unsupported, defined by Solaris. */ 155 156 /* Treat ARG as `size_t *', and store there the TLS module ID 157 of this object's PT_TLS segment, as used in TLS relocations; 158 store zero if this object does not define a PT_TLS segment. */ 159 RTLD_DI_TLS_MODID = 9, 160 161 /* Treat ARG as `void **', and store there a pointer to the calling 162 thread's TLS block corresponding to this object's PT_TLS segment. 163 Store a null pointer if this object does not define a PT_TLS 164 segment, or if the calling thread has not allocated a block for it. */ 165 RTLD_DI_TLS_DATA = 10, 166 167 RTLD_DI_MAX = 10 168 }; 169 170 171 /* This is the type of elements in `Dl_serinfo', below. 172 The `dls_name' member points to space in the buffer passed to `dlinfo'. */ 173 typedef struct 174 { 175 char *dls_name; /* Name of library search path directory. */ 176 unsigned int dls_flags; /* Indicates where this directory came from. */ 177 } Dl_serpath; 178 179 /* This is the structure that must be passed (by reference) to `dlinfo' for 180 the RTLD_DI_SERINFO and RTLD_DI_SERINFOSIZE requests. */ 181 typedef struct 182 { 183 size_t dls_size; /* Size in bytes of the whole buffer. */ 184 unsigned int dls_cnt; /* Number of elements in `dls_serpath'. */ 185 # if __GNUC_PREREQ (3, 0) 186 /* The zero-length array avoids an unwanted array subscript check by 187 the compiler, while the surrounding anonymous union preserves the 188 historic size of the type. At the time of writing, GNU C does 189 not support structs with flexible array members in unions. */ 190 __extension__ union 191 { 192 Dl_serpath dls_serpath[0]; /* Actually longer, dls_cnt elements. */ 193 Dl_serpath __dls_serpath_pad[1]; 194 }; 195 # else 196 Dl_serpath dls_serpath[1]; /* Actually longer, dls_cnt elements. */ 197 # endif 198 } Dl_serinfo; 199 200 struct dl_find_object 201 { 202 __extension__ unsigned long long int dlfo_flags; 203 void *dlfo_map_start; /* Beginning of mapping containing address. */ 204 void *dlfo_map_end; /* End of mapping. */ 205 struct link_map *dlfo_link_map; 206 void *dlfo_eh_frame; /* Exception handling data of the object. */ 207 # if DLFO_STRUCT_HAS_EH_DBASE 208 void *dlfo_eh_dbase; /* Base address for DW_EH_PE_datarel. */ 209 # if __WORDSIZE == 32 210 unsigned int __dlfo_eh_dbase_pad; 211 # endif 212 # endif 213 # if DLFO_STRUCT_HAS_EH_COUNT 214 int dlfo_eh_count; /* Number of exception handling entries. */ 215 unsigned int __dlfo_eh_count_pad; 216 # endif 217 __extension__ unsigned long long int __dflo_reserved[7]; 218 }; 219 220 /* If ADDRESS is found in an object, fill in *RESULT and return 0. 221 Otherwise, return -1. */ 222 int _dl_find_object (void *__address, struct dl_find_object *__result) __THROW; 223 224 #endif /* __USE_GNU */ 225 226 227 __END_DECLS 228 229 #endif /* dlfcn.h */ 230