]>
Commit | Line | Data |
---|---|---|
5d28a896 FW |
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 | ||
8 | The @dfn{dynamic linker} is responsible for loading dynamically linked | |
9 | programs and their dependencies (in the form of shared objects). The | |
10 | dynamic linker in @theglibc{} also supports loading shared objects (such | |
11 | as plugins) later at run time. | |
12 | ||
13 | Dynamic 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 | |
23 | dynamic linker. | |
24 | ||
93804a1e FW |
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} | |
28 | This function returns information about @var{handle} in the memory | |
29 | location @var{arg}, based on @var{request}. The @var{handle} argument | |
30 | must be a pointer returned by @code{dlopen} or @code{dlmopen}; it must | |
31 | not have been closed by @code{dlclose}. | |
32 | ||
d056c212 FW |
33 | On success, @code{dlinfo} returns 0 for most request types; exceptions |
34 | are noted below. If there is an error, the function returns @math{-1}, | |
35 | and @code{dlerror} can be used to obtain a corresponding error message. | |
93804a1e FW |
36 | |
37 | The following operations are defined for use with @var{request}: | |
38 | ||
39 | @vtable @code | |
40 | @item RTLD_DI_LINKMAP | |
41 | The corresponding @code{struct link_map} pointer for @var{handle} is | |
42 | written to @code{*@var{arg}}. The @var{arg} argument must be the | |
43 | address of an object of type @code{struct link_map *}. | |
44 | ||
45 | @item RTLD_DI_LMID | |
46 | The namespace identifier of @var{handle} is written to | |
47 | @code{*@var{arg}}. The @var{arg} argument must be the address of an | |
48 | object of type @code{Lmid_t}. | |
49 | ||
50 | @item RTLD_DI_ORIGIN | |
51 | The value of the @code{$ORIGIN} dynamic string token for @var{handle} is | |
52 | written to the character array starting at @var{arg} as a | |
53 | null-terminated string. | |
54 | ||
55 | This request type should not be used because it is prone to buffer | |
56 | overflows. | |
57 | ||
58 | @item RTLD_DI_SERINFO | |
59 | @itemx RTLD_DI_SERINFOSIZE | |
60 | These 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 | |
63 | be made first; it updates the @code{dls_size} and @code{dls_cnt} members | |
64 | of the @code{Dl_serinfo} object. The caller should then allocate memory | |
65 | to 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 | |
68 | the @code{dls_cnt} member in the initial @code{RTLD_DI_SERINFOSIZE} | |
69 | request. The caller is responsible for freeing the allocated buffer. | |
70 | ||
71 | This interface is prone to buffer overflows in multi-threaded processes | |
72 | because 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 | |
76 | This request writes the address of the TLS block (in the current thread) | |
77 | for the shared object identified by @var{handle} to @code{*@var{arg}}. | |
78 | The 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 | |
80 | any associated TLS block. | |
81 | ||
82 | @item RTLD_DI_TLS_MODID | |
83 | This request writes the TLS module ID for the shared object @var{handle} | |
84 | to @code{*@var{arg}}. The argument @var{arg} must be the address of an | |
85 | object of type @code{size_t}. The module ID is zero if the object | |
86 | does not have an associated TLS block. | |
d056c212 FW |
87 | |
88 | @item RTLD_DI_PHDR | |
89 | This request writes the address of the program header array to | |
90 | @code{*@var{arg}}. The argument @var{arg} must be the address of an | |
91 | object of type @code{const ElfW(Phdr) *} (that is, | |
92 | @code{const Elf32_Phdr *} or @code{const Elf64_Phdr *}, as appropriate | |
93 | for the current architecture). For this request, the value returned by | |
94 | @code{dlinfo} is the number of program headers in the program header | |
95 | array. | |
93804a1e FW |
96 | @end vtable |
97 | ||
98 | The @code{dlinfo} function is a GNU extension. | |
99 | @end deftypefun | |
100 | ||
101 | The remainder of this section documents the @code{_dl_find_object} | |
102 | function and supporting types and constants. | |
103 | ||
5d28a896 FW |
104 | @deftp {Data Type} {struct dl_find_object} |
105 | @standards{GNU, dlfcn.h} | |
106 | This structure contains information about a main program or loaded | |
107 | object. The @code{_dl_find_object} function uses it to return | |
108 | result data to the caller. | |
109 | ||
110 | @table @code | |
111 | @item unsigned long long int dlfo_flags | |
112 | Currently unused and always 0. | |
113 | ||
114 | @item void *dlfo_map_start | |
115 | The start address of the inspected mapping. This information comes from | |
116 | the program header, so it follows its convention, and the address is not | |
117 | necessarily page-aligned. | |
118 | ||
119 | @item void *dlfo_map_end | |
120 | The end address of the mapping. | |
121 | ||
122 | @item struct link_map *dlf_link_map | |
123 | This member contains a pointer to the link map of the object. | |
124 | ||
125 | @item struct link_map *dlf_link_map | |
126 | This member contains a pointer to the exception handling data of the | |
127 | object. See @code{DLFO_EH_SEGMENT_TYPE} below. | |
128 | ||
129 | @end table | |
130 | ||
131 | This structure is a GNU extension. | |
132 | @end deftp | |
133 | ||
134 | @deftypevr Macro int DLFO_STRUCT_HAS_EH_DBASE | |
135 | @standards{GNU, dlfcn.h} | |
136 | On 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 | ||
141 | This macro is a GNU extension. | |
142 | @end deftypevr | |
143 | ||
144 | @deftypevr Macro int DLFO_STRUCT_HAS_EH_COUNT | |
145 | @standards{GNU, dlfcn.h} | |
146 | On 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 | |
149 | handling entries in the EH frame segment identified by the | |
150 | @code{dlfo_eh_frame} member. | |
151 | ||
152 | This macro is a GNU extension. | |
153 | @end deftypevr | |
154 | ||
155 | @deftypevr Macro int DLFO_EH_SEGMENT_TYPE | |
156 | @standards{GNU, dlfcn.h} | |
157 | On 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} | |
160 | segment of the object. On targets that use other unwinding formats, the | |
161 | macro expands to the program header type for the unwinding data. | |
162 | ||
163 | This 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{}} | |
169 | On success, this function returns 0 and writes about the object | |
170 | surrounding the address to @code{*@var{result}}. On failure, -1 is | |
171 | returned. | |
172 | ||
173 | The @var{address} can be a code address or data address. On | |
174 | architectures using function descriptors, no attempt is made to decode | |
175 | the function descriptor. Depending on how these descriptors are | |
176 | implemented, @code{_dl_find_object} may return the object that defines | |
177 | the function descriptor (and not the object that contains the code | |
178 | implementing the function), or fail to find any object at all. | |
179 | ||
180 | On 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 | |
183 | located within the reported mapping. | |
184 | ||
185 | This function returns a pointer to the unwinding information for the | |
186 | object that contains the program code @var{address} in | |
187 | @code{@var{result}->dlfo_eh_frame}. If the platform uses DWARF | |
188 | unwinding information, this is the in-memory address of the | |
189 | @code{PT_GNU_EH_FRAME} segment. See @code{DLFO_EH_SEGMENT_TYPE} above. | |
190 | In case @var{address} resides in an object that lacks unwinding information, | |
191 | the function still returns 0, but sets @code{@var{result}->dlfo_eh_frame} | |
192 | to a null pointer. | |
193 | ||
194 | @code{_dl_find_object} itself is thread-safe. However, if the | |
195 | application invokes @code{dlclose} for the object that contains | |
196 | @var{address} concurrently with @code{_dl_find_object} or after the call | |
197 | returns, accessing the unwinding data for that object or the link map | |
198 | (through @code{@var{result}->dlfo_link_map}) is not safe. Therefore, the | |
199 | application needs to ensure by other means (e.g., by convention) that | |
200 | @var{address} remains a valid code address while the unwinding | |
201 | information is processed. | |
202 | ||
203 | This 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 | |
5d28a896 FW |
212 | @c dlmopen |
213 | @c dlopen | |
214 | @c dlsym | |
215 | @c dlvsym |