mount_setattr.2: Further tweaks after feedback from Christian Brauner
[man-pages.git] / man3 / dlinfo.3
blob6f82fa65d0e86b368d69c64065332dcd4e1cb0bc
1 .\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com>
2 .\"
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
7 .\"
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
12 .\"
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein.  The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
19 .\" professionally.
20 .\"
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" %%%LICENSE_END
24 .\"
25 .TH DLINFO 3 2021-03-22 "Linux" "Linux Programmer's Manual"
26 .SH NAME
27 dlinfo \- obtain information about a dynamically loaded object
28 .SH SYNOPSIS
29 .nf
30 .B #define _GNU_SOURCE
31 .B #include <link.h>
32 .B #include <dlfcn.h>
33 .PP
34 .BR "int dlinfo(void *restrict " handle ", int " request \
35 ", void *restrict " info );
36 .PP
37 Link with \fI\-ldl\fP.
38 .fi
39 .SH DESCRIPTION
40 The
41 .BR dlinfo ()
42 function obtains information about the dynamically loaded object
43 referred to by
44 .IR handle
45 (typically obtained by an earlier call to
46 .BR dlopen (3)
48 .BR dlmopen (3)).
49 The
50 .I request
51 argument specifies which information is to be returned.
52 The
53 .I info
54 argument is a pointer to a buffer used to store information
55 returned by the call; the type of this argument depends on
56 .IR request .
57 .PP
58 The following values are supported for
59 .IR request
60 (with the corresponding type for
61 .IR info
62 shown in parentheses):
63 .TP
64 .BR RTLD_DI_LMID " (\fILmid_t *\fP)"
65 Obtain the ID of the link-map list (namespace) in which
66 .I handle
67 is loaded.
68 .TP
69 .BR RTLD_DI_LINKMAP " (\fIstruct link_map **\fP)"
70 Obtain a pointer to the
71 .I link_map
72 structure corresponding to
73 .IR handle .
74 The
75 .IR info
76 argument points to a pointer to a
77 .I link_map
78 structure, defined in
79 .I <link.h>
80 as:
81 .IP
82 .in +4n
83 .EX
84 struct link_map {
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
89                            object was found */
90     ElfW(Dyn) *l_ld;    /* Dynamic section of the
91                            shared object */
92     struct link_map *l_next, *l_prev;
93                         /* Chain of loaded objects */
95     /* Plus additional fields private to the
96        implementation */
98 .EE
99 .in
101 .BR RTLD_DI_ORIGIN " (\fIchar *\fP)"
102 Copy the pathname of the origin of the shared object corresponding to
103 .IR handle
104 to the location pointed to by
105 .IR info .
107 .BR RTLD_DI_SERINFO " (\fIDl_serinfo *\fP)"
108 Obtain the library search paths for the shared object referred to by
109 .IR handle .
111 .I info
112 argument is a pointer to a
113 .I Dl_serinfo
114 that contains the search paths.
115 Because the number of search paths may vary,
116 the size of the structure pointed to by
117 .IR info
118 can vary.
120 .B RTLD_DI_SERINFOSIZE
121 request described below allows applications to size the buffer suitably.
122 The caller must perform the following steps:
124 .IP 1. 3
125 Use a
126 .B RTLD_DI_SERINFOSIZE
127 request to populate a
128 .I Dl_serinfo
129 structure with the size
130 .RI ( dls_size )
131 of the structure needed for the subsequent
132 .B RTLD_DI_SERINFO
133 request.
134 .IP 2.
135 Allocate a
136 .I Dl_serinfo
137 buffer of the correct size
138 .RI ( dls_size ).
139 .IP 3.
140 Use a further
141 .B RTLD_DI_SERINFOSIZE
142 request to populate the
143 .I dls_size
145 .I dls_cnt
146 fields of the buffer allocated in the previous step.
147 .IP 4.
148 Use a
149 .B RTLD_DI_SERINFO
150 to obtain the library search paths.
154 .I Dl_serinfo
155 structure is defined as follows:
157 .in +4n
159 typedef struct {
160     size_t dls_size;           /* Size in bytes of
161                                   the whole buffer */
162     unsigned int dls_cnt;      /* Number of elements
163                                   in \(aqdls_serpath\(aq */
164     Dl_serpath dls_serpath[1]; /* Actually longer,
165                                   \(aqdls_cnt\(aq elements */
166 } Dl_serinfo;
170 Each of the
171 .I dls_serpath
172 elements in the above structure is a structure of the following form:
174 .in +4n
176 typedef struct {
177     char *dls_name;            /* Name of library search
178                                   path directory */
179     unsigned int dls_flags;    /* Indicates where this
180                                   directory came from */
181 } Dl_serpath;
186 .I dls_flags
187 field is currently unused, and always contains zero.
189 .BR RTLD_DI_SERINFOSIZE " (\fIDl_serinfo *\fP)"
190 Populate the
191 .I dls_size
193 .I dls_cnt
194 fields of the
195 .I Dl_serinfo
196 structure pointed to by
197 .IR info
198 with values suitable for allocating a buffer for use in a subsequent
199 .B RTLD_DI_SERINFO
200 request.
202 .BR RTLD_DI_TLS_MODID " (\fIsize_t *\fP, since glibc 2.4)"
203 Obtain the module ID of this shared object's TLS (thread-local storage)
204 segment, as used in TLS relocations.
205 If this object does not define a TLS segment, zero is placed in
206 .IR *info .
208 .BR RTLD_DI_TLS_DATA " (\fIvoid **\fP, since glibc 2.4)"
209 Obtain a pointer to the calling
210 thread's TLS block corresponding to this shared object's TLS segment.
211 If this object does not define a PT_TLS segment,
212 or if the calling thread has not allocated a block for it,
213 NULL is placed in
214 .IR *info .
215 .SH RETURN VALUE
216 On success,
217 .BR dlinfo ()
218 returns 0.
219 On failure, it returns \-1; the cause of the error can be diagnosed using
220 .BR dlerror (3).
221 .SH VERSIONS
222 .BR dlinfo ()
223 first appeared in glibc 2.3.3.
224 .SH ATTRIBUTES
225 For an explanation of the terms used in this section, see
226 .BR attributes (7).
227 .ad l
230 allbox;
231 lbx lb lb
232 l l l.
233 Interface       Attribute       Value
235 .BR dlinfo ()
236 T}      Thread safety   MT-Safe
240 .sp 1
241 .SH CONFORMING TO
242 This function is a nonstandard GNU extension.
243 .SH NOTES
244 This function derives from the Solaris function of the same name
245 and also appears on some other systems.
246 The sets of requests supported by the various implementations
247 overlaps only partially.
248 .SH EXAMPLES
249 The program below opens a shared objects using
250 .BR dlopen (3)
251 and then uses the
252 .B RTLD_DI_SERINFOSIZE
254 .B RTLD_DI_SERINFO
255 requests to obtain the library search path list for the library.
256 Here is an example of what we might see when running the program:
258 .in +4n
260 $ \fB./a.out /lib64/libm.so.6\fP
261 dls_serpath[0].dls_name = /lib64
262 dls_serpath[1].dls_name = /usr/lib64
265 .SS Program source
268 #define _GNU_SOURCE
269 #include <dlfcn.h>
270 #include <link.h>
271 #include <stdio.h>
272 #include <stdlib.h>
275 main(int argc, char *argv[])
277     void *handle;
278     Dl_serinfo serinfo;
279     Dl_serinfo *sip;
281     if (argc != 2) {
282         fprintf(stderr, "Usage: %s <libpath>\en", argv[0]);
283         exit(EXIT_FAILURE);
284     }
286     /* Obtain a handle for shared object specified on command line. */
288     handle = dlopen(argv[1], RTLD_NOW);
289     if (handle == NULL) {
290         fprintf(stderr, "dlopen() failed: %s\en", dlerror());
291         exit(EXIT_FAILURE);
292     }
294     /* Discover the size of the buffer that we must pass to
295        RTLD_DI_SERINFO. */
297     if (dlinfo(handle, RTLD_DI_SERINFOSIZE, &serinfo) == \-1) {
298         fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\en", dlerror());
299         exit(EXIT_FAILURE);
300     }
302     /* Allocate the buffer for use with RTLD_DI_SERINFO. */
304     sip = malloc(serinfo.dls_size);
305     if (sip == NULL) {
306         perror("malloc");
307         exit(EXIT_FAILURE);
308     }
310     /* Initialize the \(aqdls_size\(aq and \(aqdls_cnt\(aq fields in the newly
311        allocated buffer. */
313     if (dlinfo(handle, RTLD_DI_SERINFOSIZE, sip) == \-1) {
314         fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\en", dlerror());
315         exit(EXIT_FAILURE);
316     }
318     /* Fetch and print library search list. */
320     if (dlinfo(handle, RTLD_DI_SERINFO, sip) == \-1) {
321         fprintf(stderr, "RTLD_DI_SERINFO failed: %s\en", dlerror());
322         exit(EXIT_FAILURE);
323     }
325     for (int j = 0; j < serinfo.dls_cnt; j++)
326         printf("dls_serpath[%d].dls_name = %s\en",
327                 j, sip\->dls_serpath[j].dls_name);
329     exit(EXIT_SUCCESS);
332 .SH SEE ALSO
333 .BR dl_iterate_phdr (3),
334 .BR dladdr (3),
335 .BR dlerror (3),
336 .BR dlopen (3),
337 .BR dlsym (3),
338 .BR ld.so (8)