Debian Codegraph @

upstream/debian-unstable/man3/dlinfo.3

raw
1 '\" t
2 .\" Copyright 2015, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH dlinfo 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 dlinfo \- obtain information about a dynamically loaded object
10 .SH LIBRARY
11 Dynamic linking library
12 .RI ( libdl ,\~ \-ldl )
13 .SH SYNOPSIS
14 .nf
15 .B #define _GNU_SOURCE
16 .B #include <link.h>
17 .B #include <dlfcn.h>
18 .P
19 .BR "int dlinfo(void *restrict " handle ", int " request \
20 ", void *restrict " info );
21 .fi
22 .SH DESCRIPTION
23 The
24 .BR dlinfo ()
25 function obtains information about the dynamically loaded object
26 referred to by
27 .I handle
28 (typically obtained by an earlier call to
29 .BR dlopen (3)
30 or
31 .BR dlmopen (3)).
32 The
33 .I request
34 argument specifies which information is to be returned.
35 The
36 .I info
37 argument is a pointer to a buffer used to store information
38 returned by the call;
39 the type of this argument depends on
40 .IR request .
41 .P
42 The following values are supported for
43 .I request
44 (with the corresponding type for
45 .I info
46 shown in parentheses):
47 .TP
48 .BR RTLD_DI_LMID " (\f[I]Lmid_t *\f[])"
49 Obtain the ID of the link-map list (namespace) in which
50 .I handle
51 is loaded.
52 .TP
53 .BR RTLD_DI_LINKMAP " (\f[I]struct link_map **\f[])"
54 Obtain a pointer to the
55 .I link_map
56 structure corresponding to
57 .IR handle .
58 The
59 .I info
60 argument points to a pointer to a
61 .I link_map
62 structure, defined in
63 .I <link.h>
64 as:
65 .IP
66 .in +4n
67 .EX
68 struct link_map {
69 ElfW(Addr) l_addr; /* Difference between the
70 address in the ELF file and
71 the address in memory */
72 char *l_name; /* Absolute pathname where
73 object was found */
74 ElfW(Dyn) *l_ld; /* Dynamic section of the
75 shared object */
76 struct link_map *l_next, *l_prev;
77 /* Chain of loaded objects */
78 \&
79 /* Plus additional fields private to the
80 implementation */
81 };
82 .EE
83 .in
84 .TP
85 .BR RTLD_DI_ORIGIN " (\f[I]char *\f[])"
86 Copy the pathname of the origin of the shared object corresponding to
87 .I handle
88 to the location pointed to by
89 .IR info .
90 .TP
91 .BR RTLD_DI_SERINFO " (\f[I]Dl_serinfo *\f[])"
92 Obtain the library search paths for the shared object referred to by
93 .IR handle .
94 The
95 .I info
96 argument is a pointer to a
97 .I Dl_serinfo
98 that contains the search paths.
99 Because the number of search paths may vary,
100 the size of the structure pointed to by
101 .I info
102 can vary.
103 The
104 .B RTLD_DI_SERINFOSIZE
105 request described below allows applications to size the buffer suitably.
106 The caller must perform the following steps:
107 .RS
108 .IP (1) 5
109 Use a
110 .B RTLD_DI_SERINFOSIZE
111 request to populate a
112 .I Dl_serinfo
113 structure with the size
114 .RI ( dls_size )
115 of the structure needed for the subsequent
116 .B RTLD_DI_SERINFO
117 request.
118 .IP (2)
119 Allocate a
120 .I Dl_serinfo
121 buffer of the correct size
122 .RI ( dls_size ).
123 .IP (3)
124 Use a further
125 .B RTLD_DI_SERINFOSIZE
126 request to populate the
127 .I dls_size
128 and
129 .I dls_cnt
130 fields of the buffer allocated in the previous step.
131 .IP (4)
132 Use a
133 .B RTLD_DI_SERINFO
134 to obtain the library search paths.
135 .RE
136 .IP
137 The
138 .I Dl_serinfo
139 structure is defined as follows:
140 .IP
141 .in +4n
142 .EX
143 typedef struct {
144 size_t dls_size; /* Size in bytes of
145 the whole buffer */
146 unsigned int dls_cnt; /* Number of elements
147 in \[aq]dls_serpath\[aq] */
148 Dl_serpath dls_serpath[1]; /* Actually longer,
149 \[aq]dls_cnt\[aq] elements */
150 } Dl_serinfo;
151 .EE
152 .in
153 .IP
154 Each of the
155 .I dls_serpath
156 elements in the above structure is a structure of the following form:
157 .IP
158 .in +4n
159 .EX
160 typedef struct {
161 char *dls_name; /* Name of library search
162 path directory */
163 unsigned int dls_flags; /* Indicates where this
164 directory came from */
165 } Dl_serpath;
166 .EE
167 .in
168 .IP
169 The
170 .I dls_flags
171 field is currently unused, and always contains zero.
172 .TP
173 .BR RTLD_DI_SERINFOSIZE " (\f[I]Dl_serinfo *\f[])"
174 Populate the
175 .I dls_size
176 and
177 .I dls_cnt
178 fields of the
179 .I Dl_serinfo
180 structure pointed to by
181 .I info
182 with values suitable for allocating a buffer for use in a subsequent
183 .B RTLD_DI_SERINFO
184 request.
185 .TP
186 .BR RTLD_DI_TLS_MODID " (\f[I]size_t *\f[], since glibc 2.4)"
187 Obtain the module ID of this shared object's TLS (thread-local storage)
188 segment, as used in TLS relocations.
189 If this object does not define a TLS segment, zero is placed in
190 .IR *info .
191 .TP
192 .BR RTLD_DI_TLS_DATA " (\f[I]void **\f[], since glibc 2.4)"
193 Obtain a pointer to the calling
194 thread's TLS block corresponding to this shared object's TLS segment.
195 If this object does not define a PT_TLS segment,
196 or if the calling thread has not allocated a block for it,
197 NULL is placed in
198 .IR *info .
199 .TP
200 .BR RTLD_DI_PHDR " (\f[I]const ElfW(Phdr *)\f[], since glibc 2.34.1)"
201 .\" glibc commit d056c212130280c0a54d9a4f72170ec621b70ce5 (2.36)
202 .\" glibc commit 28ea43f8d64f0dd1f2de75525157730e1532e600 (2.35.1)
203 .\" glibc commit 91c2e6c3db44297bf4cb3a2e3c40236c5b6a0b23 (2.34.1)
204 Obtain the address of this shared object's program header and place it
205 in
206 .IR *info .
207 This
208 .B dlinfo
209 call returns the number of program headers in the shared object.
210 .SH RETURN VALUE
211 On success,
212 .BR dlinfo ()
213 returns 0
214 (if not specified explicitly),
215 or a positive value corresponding to the request.
216 On error, it returns \-1;
217 the error can be diagnosed using
218 .BR dlerror (3).
219 .SH ATTRIBUTES
220 For an explanation of the terms used in this section, see
221 .BR attributes (7).
222 .TS
223 allbox;
224 lbx lb lb
225 l l l.
226 Interface Attribute Value
227 T{
228 .na
229 .nh
230 .BR dlinfo ()
231 T} Thread safety MT-Safe
232 .TE
233 .SH VERSIONS
234 The sets of requests supported by the various implementations
235 overlaps only partially.
236 .SH STANDARDS
237 GNU.
238 .SH HISTORY
239 glibc 2.3.3.
240 Solaris.
241 .SH EXAMPLES
242 The program below opens a shared objects using
243 .BR dlopen (3)
244 and then uses the
245 .B RTLD_DI_SERINFOSIZE
246 and
247 .B RTLD_DI_SERINFO
248 requests to obtain the library search path list for the library.
249 Here is an example of what we might see when running the program:
250 .P
251 .in +4n
252 .EX
253 .RB $ " ./a.out /lib64/libm.so.6" ;
254 dls_serpath[0].dls_name = /lib64
255 dls_serpath[1].dls_name = /usr/lib64
256 .EE
257 .in
258 .SS Program source
259 \&
260 .\" SRC BEGIN (dlinfo.c)
261 .EX
262 #define _GNU_SOURCE
263 #include <dlfcn.h>
264 #include <link.h>
265 #include <stdio.h>
266 #include <stdlib.h>
267 \&
268 int
269 main(int argc, char *argv[])
270 {
271 void *handle;
272 Dl_serinfo serinfo;
273 Dl_serinfo *sip;
274 \&
275 if (argc != 2) {
276 fprintf(stderr, "Usage: %s <libpath>\[rs]n", argv[0]);
277 exit(EXIT_FAILURE);
278 }
279 \&
280 /* Obtain a handle for shared object specified on command line. */
281 \&
282 handle = dlopen(argv[1], RTLD_NOW);
283 if (handle == NULL) {
284 fprintf(stderr, "dlopen() failed: %s\[rs]n", dlerror());
285 exit(EXIT_FAILURE);
286 }
287 \&
288 /* Discover the size of the buffer that we must pass to
289 RTLD_DI_SERINFO. */
290 \&
291 if (dlinfo(handle, RTLD_DI_SERINFOSIZE, &serinfo) == \-1) {
292 fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\[rs]n", dlerror());
293 exit(EXIT_FAILURE);
294 }
295 \&
296 /* Allocate the buffer for use with RTLD_DI_SERINFO. */
297 \&
298 sip = malloc(serinfo.dls_size);
299 if (sip == NULL) {
300 perror("malloc");
301 exit(EXIT_FAILURE);
302 }
303 \&
304 /* Initialize the \[aq]dls_size\[aq] and \[aq]dls_cnt\[aq] fields in the newly
305 allocated buffer. */
306 \&
307 if (dlinfo(handle, RTLD_DI_SERINFOSIZE, sip) == \-1) {
308 fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\[rs]n", dlerror());
309 exit(EXIT_FAILURE);
310 }
311 \&
312 /* Fetch and print library search list. */
313 \&
314 if (dlinfo(handle, RTLD_DI_SERINFO, sip) == \-1) {
315 fprintf(stderr, "RTLD_DI_SERINFO failed: %s\[rs]n", dlerror());
316 exit(EXIT_FAILURE);
317 }
318 \&
319 for (size_t j = 0; j < serinfo.dls_cnt; j++)
320 printf("dls_serpath[%zu].dls_name = %s\[rs]n",
321 j, sip\->dls_serpath[j].dls_name);
322 \&
323 exit(EXIT_SUCCESS);
324 }
325 .EE
326 .\" SRC END
327 .SH SEE ALSO
328 .BR dl_iterate_phdr (3),
329 .BR dladdr (3),
330 .BR dlerror (3),
331 .BR dlopen (3),
332 .BR dlsym (3),
333 .BR ld.so (8)