1@node Dynamic Linker 2@c @node Dynamic Linker, Internal Probes, Threads, Top 3@c %MENU% Loading programs and shared objects. 4@chapter Dynamic Linker 5@cindex dynamic linker 6@cindex dynamic loader 7 8The @dfn{dynamic linker} is responsible for loading dynamically linked 9programs and their dependencies (in the form of shared objects). The 10dynamic linker in @theglibc{} also supports loading shared objects (such 11as plugins) later at run time. 12 13Dynamic linkers are sometimes called @dfn{dynamic loaders}. 14 15@menu 16* Dynamic Linker Introspection:: Interfaces for querying mapping information. 17@end menu 18 19@node Dynamic Linker Introspection 20@section Dynamic Linker Introspection 21 22@Theglibc{} provides various functions for querying information from the 23dynamic linker. 24 25@deftypefun {int} dlinfo (void *@var{handle}, int @var{request}, void *@var{arg}) 26@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} 27@standards{GNU, dlfcn.h} 28This function returns information about @var{handle} in the memory 29location @var{arg}, based on @var{request}. The @var{handle} argument 30must be a pointer returned by @code{dlopen} or @code{dlmopen}; it must 31not have been closed by @code{dlclose}. 32 33On success, @code{dlinfo} returns 0 for most request types; exceptions 34are noted below. If there is an error, the function returns @math{-1}, 35and @code{dlerror} can be used to obtain a corresponding error message. 36 37The following operations are defined for use with @var{request}: 38 39@vtable @code 40@item RTLD_DI_LINKMAP 41The corresponding @code{struct link_map} pointer for @var{handle} is 42written to @code{*@var{arg}}. The @var{arg} argument must be the 43address of an object of type @code{struct link_map *}. 44 45@item RTLD_DI_LMID 46The namespace identifier of @var{handle} is written to 47@code{*@var{arg}}. The @var{arg} argument must be the address of an 48object of type @code{Lmid_t}. 49 50@item RTLD_DI_ORIGIN 51The value of the @code{$ORIGIN} dynamic string token for @var{handle} is 52written to the character array starting at @var{arg} as a 53null-terminated string. 54 55This request type should not be used because it is prone to buffer 56overflows. 57 58@item RTLD_DI_SERINFO 59@itemx RTLD_DI_SERINFOSIZE 60These requests can be used to obtain search path information for 61@var{handle}. For both requests, @var{arg} must point to a 62@code{Dl_serinfo} object. The @code{RTLD_DI_SERINFOSIZE} request must 63be made first; it updates the @code{dls_size} and @code{dls_cnt} members 64of the @code{Dl_serinfo} object. The caller should then allocate memory 65to store at least @code{dls_size} bytes and pass that buffer to a 66@code{RTLD_DI_SERINFO} request. This second request fills the 67@code{dls_serpath} array. The number of array elements was returned in 68the @code{dls_cnt} member in the initial @code{RTLD_DI_SERINFOSIZE} 69request. The caller is responsible for freeing the allocated buffer. 70 71This interface is prone to buffer overflows in multi-threaded processes 72because the required size can change between the 73@code{RTLD_DI_SERINFOSIZE} and @code{RTLD_DI_SERINFO} requests. 74 75@item RTLD_DI_TLS_DATA 76This request writes the address of the TLS block (in the current thread) 77for the shared object identified by @var{handle} to @code{*@var{arg}}. 78The argument @var{arg} must be the address of an object of type 79@code{void *}. A null pointer is written if the object does not have 80any associated TLS block. 81 82@item RTLD_DI_TLS_MODID 83This request writes the TLS module ID for the shared object @var{handle} 84to @code{*@var{arg}}. The argument @var{arg} must be the address of an 85object of type @code{size_t}. The module ID is zero if the object 86does not have an associated TLS block. 87 88@item RTLD_DI_PHDR 89This request writes the address of the program header array to 90@code{*@var{arg}}. The argument @var{arg} must be the address of an 91object of type @code{const ElfW(Phdr) *} (that is, 92@code{const Elf32_Phdr *} or @code{const Elf64_Phdr *}, as appropriate 93for the current architecture). For this request, the value returned by 94@code{dlinfo} is the number of program headers in the program header 95array. 96@end vtable 97 98The @code{dlinfo} function is a GNU extension. 99@end deftypefun 100 101The remainder of this section documents the @code{_dl_find_object} 102function and supporting types and constants. 103 104@deftp {Data Type} {struct dl_find_object} 105@standards{GNU, dlfcn.h} 106This structure contains information about a main program or loaded 107object. The @code{_dl_find_object} function uses it to return 108result data to the caller. 109 110@table @code 111@item unsigned long long int dlfo_flags 112Currently unused and always 0. 113 114@item void *dlfo_map_start 115The start address of the inspected mapping. This information comes from 116the program header, so it follows its convention, and the address is not 117necessarily page-aligned. 118 119@item void *dlfo_map_end 120The end address of the mapping. 121 122@item struct link_map *dlf_link_map 123This member contains a pointer to the link map of the object. 124 125@item struct link_map *dlf_link_map 126This member contains a pointer to the exception handling data of the 127object. See @code{DLFO_EH_SEGMENT_TYPE} below. 128 129@end table 130 131This structure is a GNU extension. 132@end deftp 133 134@deftypevr Macro int DLFO_STRUCT_HAS_EH_DBASE 135@standards{GNU, dlfcn.h} 136On most targets, this macro is defined as @code{0}. If it is defined to 137@code{1}, @code{struct dl_find_object} contains an additional member 138@code{dlfo_eh_dbase} of type @code{void *}. It is the base address for 139@code{DW_EH_PE_datarel} DWARF encodings to this location. 140 141This macro is a GNU extension. 142@end deftypevr 143 144@deftypevr Macro int DLFO_STRUCT_HAS_EH_COUNT 145@standards{GNU, dlfcn.h} 146On most targets, this macro is defined as @code{0}. If it is defined to 147@code{1}, @code{struct dl_find_object} contains an additional member 148@code{dlfo_eh_count} of type @code{int}. It is the number of exception 149handling entries in the EH frame segment identified by the 150@code{dlfo_eh_frame} member. 151 152This macro is a GNU extension. 153@end deftypevr 154 155@deftypevr Macro int DLFO_EH_SEGMENT_TYPE 156@standards{GNU, dlfcn.h} 157On targets using DWARF-based exception unwinding, this macro expands to 158@code{PT_GNU_EH_FRAME}. This indicates that @code{dlfo_eh_frame} in 159@code{struct dl_find_object} points to the @code{PT_GNU_EH_FRAME} 160segment of the object. On targets that use other unwinding formats, the 161macro expands to the program header type for the unwinding data. 162 163This macro is a GNU extension. 164@end deftypevr 165 166@deftypefun {int} _dl_find_object (void *@var{address}, struct dl_find_object *@var{result}) 167@standards{GNU, dlfcn.h} 168@safety{@mtsafe{}@assafe{}@acsafe{}} 169On success, this function returns 0 and writes about the object 170surrounding the address to @code{*@var{result}}. On failure, -1 is 171returned. 172 173The @var{address} can be a code address or data address. On 174architectures using function descriptors, no attempt is made to decode 175the function descriptor. Depending on how these descriptors are 176implemented, @code{_dl_find_object} may return the object that defines 177the function descriptor (and not the object that contains the code 178implementing the function), or fail to find any object at all. 179 180On success @var{address} is greater than or equal to 181@code{@var{result}->dlfo_map_start} and less than 182@code{@var{result}->dlfo_map_end}, that is, the supplied code address is 183located within the reported mapping. 184 185This function returns a pointer to the unwinding information for the 186object that contains the program code @var{address} in 187@code{@var{result}->dlfo_eh_frame}. If the platform uses DWARF 188unwinding information, this is the in-memory address of the 189@code{PT_GNU_EH_FRAME} segment. See @code{DLFO_EH_SEGMENT_TYPE} above. 190In case @var{address} resides in an object that lacks unwinding information, 191the function still returns 0, but sets @code{@var{result}->dlfo_eh_frame} 192to a null pointer. 193 194@code{_dl_find_object} itself is thread-safe. However, if the 195application invokes @code{dlclose} for the object that contains 196@var{address} concurrently with @code{_dl_find_object} or after the call 197returns, accessing the unwinding data for that object or the link map 198(through @code{@var{result}->dlfo_link_map}) is not safe. Therefore, the 199application needs to ensure by other means (e.g., by convention) that 200@var{address} remains a valid code address while the unwinding 201information is processed. 202 203This function is a GNU extension. 204@end deftypefun 205 206 207@c FIXME these are undocumented: 208@c dladdr 209@c dladdr1 210@c dlclose 211@c dlerror 212@c dlmopen 213@c dlopen 214@c dlsym 215@c dlvsym 216