2 .\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .TH DLINFO 3 2017-09-15 "Linux" "Linux Programmer's Manual"
28 dlinfo \- obtain information about a dynamically loaded object
31 .B #define _GNU_SOURCE
35 .BR "int dlinfo(void *" handle ", int " request ", void *" info );
37 Link with \fI\-ldl\fP.
42 function obtains information about the dynamically loaded object
45 (typically obtained by an earlier call to
51 argument specifies which information is to be returned.
54 argument is a pointer to a buffer used to store information
55 returned by the call; the type of this argument depends on
58 The following values are supported for
60 (with the corresponding type for
62 shown in parentheses):
64 .BR RTLD_DI_LMID " (\fILmid_t *\fP)"
65 Obtain the ID of the link-map list (namespace) in which
69 .BR RTLD_DI_LINKMAP " (\fIstruct link_map **\fP)"
70 Obtain a pointer to the
72 structure corresponding to
76 argument points to a pointer to a
85 ElfW(Addr) l_addr; /* Difference between the
86 address in the ELF file and
87 the address in memory */
88 char *l_name; /* Absolute pathname where
90 ElfW(Dyn) *l_ld; /* Dynamic section of the
92 struct link_map *l_next, *l_prev;
93 /* Chain of loaded objects */
95 /* Plus additional fields private to the
101 .BR RTLD_DI_ORIGIN " (\fIchar *\fP)"
102 Copy the pathname of the origin of the shared object corresponding to
104 to the location pointed to by
107 .BR RTLD_DI_SERINFO " (\fIDl_serinfo *\fP)"
108 Obtain the library search paths for the shared object referred to by
112 argument is a pointer to a
114 that contains the search paths.
115 Because the number of search paths may vary,
116 the size of the structure pointed to by
120 .B RTLD_DI_SERINFOSIZE
121 request described below allows applications to size the buffer suitably.
122 The caller must perform the following steps:
126 .B RTLD_DI_SERINFOSIZE
127 request to populate a
129 structure with the size
131 of the structure needed for the subsequent
137 buffer of the correct size
141 .B RTLD_DI_SERINFOSIZE
142 request to populate the
146 fields of the buffer allocated in the previous step.
150 to obtain the library search paths.
156 structure is defined as follows:
161 size_t dls_size; /* Size in bytes of
163 unsigned int dls_cnt; /* Number of elements
165 Dl_serpath dls_serpath[1]; /* Actually longer,
166 'dls_cnt' elements */
173 elements in the above structure is a structure of the following form:
178 char *dls_name; /* Name of library search
180 unsigned int dls_flags; /* Indicates where this
181 directory came from */
188 field is currently unused, and always contains zero.
190 .BR RTLD_DI_SERINFOSIZE " (\fIDl_serinfo *\fP)"
197 structure pointed to by
199 with values suitable for allocating a buffer for use in a subsequent
203 .BR RTLD_DI_TLS_MODID " (\fIsize_t *\fP, since glibc 2.4)"
204 Obtain the module ID of this shared object's TLS (thread-local storage)
205 segment, as used in TLS relocations.
206 If this object does not define a TLS segment, zero is placed in
209 .BR RTLD_DI_TLS_DATA " (\fIvoid **\fP, since glibc 2.4)"
210 Obtain a pointer to the calling
211 thread's TLS block corresponding to this shared object's TLS segment.
212 If this object does not define a PT_TLS segment,
213 or if the calling thread has not allocated a block for it,
220 On failure, it returns \-1; the cause of the error can be diagnosed using
224 first appeared in glibc 2.3.3.
226 For an explanation of the terms used in this section, see
232 Interface Attribute Value
235 T} Thread safety MT-Safe
238 This function is a nonstandard GNU extension.
240 This function derives from the Solaris function of the same name
241 and also appears on some other systems.
242 The sets of requests supported by the various implementations
243 overlaps only partially.
245 The program below opens a shared objects using
248 .B RTLD_DI_SERINFOSIZE
251 requests to obtain the library search path list for the library.
252 Here is an example of what we might see when running the program:
256 $ \fB./a.out /lib64/libm.so.6\fP
257 dls_serpath[0].dls_name = /lib64
258 dls_serpath[1].dls_name = /usr/lib64
271 main(int argc, char *argv[])
279 fprintf(stderr, "Usage: %s <libpath>\\n", argv[0]);
283 /* Obtain a handle for shared object specified on command line */
285 handle = dlopen(argv[1], RTLD_NOW);
286 if (handle == NULL) {
287 fprintf(stderr, "dlopen() failed: %s\\n", dlerror());
291 /* Discover the size of the buffer that we must pass to
294 if (dlinfo(handle, RTLD_DI_SERINFOSIZE, &serinfo) == \-1) {
295 fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\\n", dlerror());
299 /* Allocate the buffer for use with RTLD_DI_SERINFO */
301 sip = malloc(serinfo.dls_size);
307 /* Initialize the \(aqdls_size\(aq and \(aqdls_cnt\(aq fields in the newly
310 if (dlinfo(handle, RTLD_DI_SERINFOSIZE, sip) == \-1) {
311 fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\\n", dlerror());
315 /* Fetch and print library search list */
317 if (dlinfo(handle, RTLD_DI_SERINFO, sip) == \-1) {
318 fprintf(stderr, "RTLD_DI_SERINFO failed: %s\\n", dlerror());
322 for (j = 0; j < serinfo.dls_cnt; j++)
323 printf("dls_serpath[%d].dls_name = %s\\n",
324 j, sip\->dls_serpath[j].dls_name);
330 .BR dl_iterate_phdr (3),