Debian Codegraph @

upstream/debian-trixie/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-06-15 "Linux man-pages 6.9.1"
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 .SH RETURN VALUE
198 On success,
199 .BR dlinfo ()
200 returns 0.
201 On failure, it returns \-1; the cause of the error can be diagnosed using
202 .BR dlerror (3).
203 .SH ATTRIBUTES
204 For an explanation of the terms used in this section, see
205 .BR attributes (7).
206 .TS
207 allbox;
208 lbx lb lb
209 l l l.
210 Interface Attribute Value
211 T{
212 .na
213 .nh
214 .BR dlinfo ()
215 T} Thread safety MT-Safe
216 .TE
217 .SH VERSIONS
218 The sets of requests supported by the various implementations
219 overlaps only partially.
220 .SH STANDARDS
221 GNU.
222 .SH HISTORY
223 glibc 2.3.3.
224 Solaris.
225 .SH EXAMPLES
226 The program below opens a shared objects using
227 .BR dlopen (3)
228 and then uses the
229 .B RTLD_DI_SERINFOSIZE
230 and
231 .B RTLD_DI_SERINFO
232 requests to obtain the library search path list for the library.
233 Here is an example of what we might see when running the program:
234 .P
235 .in +4n
236 .EX
237 $ \fB./a.out /lib64/libm.so.6\fP
238 dls_serpath[0].dls_name = /lib64
239 dls_serpath[1].dls_name = /usr/lib64
240 .EE
241 .in
242 .SS Program source
243 \&
244 .\" SRC BEGIN (dlinfo.c)
245 .EX
246 #define _GNU_SOURCE
247 #include <dlfcn.h>
248 #include <link.h>
249 #include <stdio.h>
250 #include <stdlib.h>
251 \&
252 int
253 main(int argc, char *argv[])
254 {
255 void *handle;
256 Dl_serinfo serinfo;
257 Dl_serinfo *sip;
258 \&
259 if (argc != 2) {
260 fprintf(stderr, "Usage: %s <libpath>\[rs]n", argv[0]);
261 exit(EXIT_FAILURE);
262 }
263 \&
264 /* Obtain a handle for shared object specified on command line. */
265 \&
266 handle = dlopen(argv[1], RTLD_NOW);
267 if (handle == NULL) {
268 fprintf(stderr, "dlopen() failed: %s\[rs]n", dlerror());
269 exit(EXIT_FAILURE);
270 }
271 \&
272 /* Discover the size of the buffer that we must pass to
273 RTLD_DI_SERINFO. */
274 \&
275 if (dlinfo(handle, RTLD_DI_SERINFOSIZE, &serinfo) == \-1) {
276 fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\[rs]n", dlerror());
277 exit(EXIT_FAILURE);
278 }
279 \&
280 /* Allocate the buffer for use with RTLD_DI_SERINFO. */
281 \&
282 sip = malloc(serinfo.dls_size);
283 if (sip == NULL) {
284 perror("malloc");
285 exit(EXIT_FAILURE);
286 }
287 \&
288 /* Initialize the \[aq]dls_size\[aq] and \[aq]dls_cnt\[aq] fields in the newly
289 allocated buffer. */
290 \&
291 if (dlinfo(handle, RTLD_DI_SERINFOSIZE, sip) == \-1) {
292 fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\[rs]n", dlerror());
293 exit(EXIT_FAILURE);
294 }
295 \&
296 /* Fetch and print library search list. */
297 \&
298 if (dlinfo(handle, RTLD_DI_SERINFO, sip) == \-1) {
299 fprintf(stderr, "RTLD_DI_SERINFO failed: %s\[rs]n", dlerror());
300 exit(EXIT_FAILURE);
301 }
302 \&
303 for (size_t j = 0; j < serinfo.dls_cnt; j++)
304 printf("dls_serpath[%zu].dls_name = %s\[rs]n",
305 j, sip\->dls_serpath[j].dls_name);
306 \&
307 exit(EXIT_SUCCESS);
308 }
309 .EE
310 .\" SRC END
311 .SH SEE ALSO
312 .BR dl_iterate_phdr (3),
313 .BR dladdr (3),
314 .BR dlerror (3),
315 .BR dlopen (3),
316 .BR dlsym (3),
317 .BR ld.so (8)