Debian Codegraph @

upstream/fedora-44/man3/dlinfo.3

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