1dlinfo(3)                  Library Functions Manual                  dlinfo(3)
2
3
4

NAME

6       dlinfo - obtain information about a dynamically loaded object
7

LIBRARY

9       Dynamic linking library (libdl, -ldl)
10

SYNOPSIS

12       #define _GNU_SOURCE
13       #include <link.h>
14       #include <dlfcn.h>
15
16       int dlinfo(void *restrict handle, int request, void *restrict info);
17

DESCRIPTION

19       The  dlinfo() function obtains information about the dynamically loaded
20       object referred to by handle (typically obtained by an earlier call  to
21       dlopen(3)  or dlmopen(3)).  The request argument specifies which infor‐
22       mation is to be returned.  The info argument is a pointer to  a  buffer
23       used  to store information returned by the call; the type of this argu‐
24       ment depends on request.
25
26       The following values are supported for request (with the  corresponding
27       type for info shown in parentheses):
28
29       RTLD_DI_LMID (Lmid_t *)
30              Obtain  the  ID of the link-map list (namespace) in which handle
31              is loaded.
32
33       RTLD_DI_LINKMAP (struct link_map **)
34              Obtain a pointer to the link_map structure corresponding to han‐
35              dle.  The info argument points to a pointer to a link_map struc‐
36              ture, defined in <link.h> as:
37
38                  struct link_map {
39                      ElfW(Addr) l_addr;  /* Difference between the
40                                             address in the ELF file and
41                                             the address in memory */
42                      char      *l_name;  /* Absolute pathname where
43                                             object was found */
44                      ElfW(Dyn) *l_ld;    /* Dynamic section of the
45                                             shared object */
46                      struct link_map *l_next, *l_prev;
47                                          /* Chain of loaded objects */
48
49                      /* Plus additional fields private to the
50                         implementation */
51                  };
52
53       RTLD_DI_ORIGIN (char *)
54              Copy the pathname of the origin of the shared object correspond‐
55              ing to handle to the location pointed to by info.
56
57       RTLD_DI_SERINFO (Dl_serinfo *)
58              Obtain  the  library search paths for the shared object referred
59              to by handle.  The info argument is a pointer  to  a  Dl_serinfo
60              that  contains  the  search paths.  Because the number of search
61              paths may vary, the size of the structure pointed to by info can
62              vary.   The  RTLD_DI_SERINFOSIZE  request described below allows
63              applications to size the buffer suitably.  The caller must  per‐
64              form the following steps:
65
66              (1)  Use  a RTLD_DI_SERINFOSIZE request to populate a Dl_serinfo
67                   structure with the size (dls_size) of the structure  needed
68                   for the subsequent RTLD_DI_SERINFO request.
69
70              (2)  Allocate   a   Dl_serinfo   buffer   of  the  correct  size
71                   (dls_size).
72
73              (3)  Use a further RTLD_DI_SERINFOSIZE request to  populate  the
74                   dls_size  and dls_cnt fields of the buffer allocated in the
75                   previous step.
76
77              (4)  Use a RTLD_DI_SERINFO to obtain the library search paths.
78
79              The Dl_serinfo structure is defined as follows:
80
81                  typedef struct {
82                      size_t dls_size;           /* Size in bytes of
83                                                    the whole buffer */
84                      unsigned int dls_cnt;      /* Number of elements
85                                                    in 'dls_serpath' */
86                      Dl_serpath dls_serpath[1]; /* Actually longer,
87                                                    'dls_cnt' elements */
88                  } Dl_serinfo;
89
90              Each of the dls_serpath elements in the  above  structure  is  a
91              structure of the following form:
92
93                  typedef struct {
94                      char *dls_name;            /* Name of library search
95                                                    path directory */
96                      unsigned int dls_flags;    /* Indicates where this
97                                                    directory came from */
98                  } Dl_serpath;
99
100              The  dls_flags  field  is  currently unused, and always contains
101              zero.
102
103       RTLD_DI_SERINFOSIZE (Dl_serinfo *)
104              Populate the dls_size  and  dls_cnt  fields  of  the  Dl_serinfo
105              structure pointed to by info with values suitable for allocating
106              a buffer for use in a subsequent RTLD_DI_SERINFO request.
107
108       RTLD_DI_TLS_MODID (size_t *, since glibc 2.4)
109              Obtain the module ID of this shared object's  TLS  (thread-local
110              storage)  segment,  as  used in TLS relocations.  If this object
111              does not define a TLS segment, zero is placed in *info.
112
113       RTLD_DI_TLS_DATA (void **, since glibc 2.4)
114              Obtain a pointer to the calling thread's TLS block corresponding
115              to  this  shared  object's TLS segment.  If this object does not
116              define a PT_TLS segment, or if the calling thread has not  allo‐
117              cated a block for it, NULL is placed in *info.
118

RETURN VALUE

120       On  success,  dlinfo() returns 0.  On failure, it returns -1; the cause
121       of the error can be diagnosed using dlerror(3).
122

ATTRIBUTES

124       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
125       tributes(7).
126
127       ┌────────────────────────────────────────────┬───────────────┬─────────┐
128Interface                                   Attribute     Value   
129       ├────────────────────────────────────────────┼───────────────┼─────────┤
130dlinfo()                                    │ Thread safety │ MT-Safe │
131       └────────────────────────────────────────────┴───────────────┴─────────┘
132

VERSIONS

134       The  sets of requests supported by the various implementations overlaps
135       only partially.
136

STANDARDS

138       GNU.
139

HISTORY

141       glibc 2.3.3.  Solaris.
142

EXAMPLES

144       The program below opens a shared objects using dlopen(3) and then  uses
145       the  RTLD_DI_SERINFOSIZE and RTLD_DI_SERINFO requests to obtain the li‐
146       brary search path list for the library.  Here is an example of what  we
147       might see when running the program:
148
149           $ ./a.out /lib64/libm.so.6
150           dls_serpath[0].dls_name = /lib64
151           dls_serpath[1].dls_name = /usr/lib64
152
153   Program source
154
155       #define _GNU_SOURCE
156       #include <dlfcn.h>
157       #include <link.h>
158       #include <stdio.h>
159       #include <stdlib.h>
160
161       int
162       main(int argc, char *argv[])
163       {
164           void *handle;
165           Dl_serinfo serinfo;
166           Dl_serinfo *sip;
167
168           if (argc != 2) {
169               fprintf(stderr, "Usage: %s <libpath>\n", argv[0]);
170               exit(EXIT_FAILURE);
171           }
172
173           /* Obtain a handle for shared object specified on command line. */
174
175           handle = dlopen(argv[1], RTLD_NOW);
176           if (handle == NULL) {
177               fprintf(stderr, "dlopen() failed: %s\n", dlerror());
178               exit(EXIT_FAILURE);
179           }
180
181           /* Discover the size of the buffer that we must pass to
182              RTLD_DI_SERINFO. */
183
184           if (dlinfo(handle, RTLD_DI_SERINFOSIZE, &serinfo) == -1) {
185               fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\n", dlerror());
186               exit(EXIT_FAILURE);
187           }
188
189           /* Allocate the buffer for use with RTLD_DI_SERINFO. */
190
191           sip = malloc(serinfo.dls_size);
192           if (sip == NULL) {
193               perror("malloc");
194               exit(EXIT_FAILURE);
195           }
196
197           /* Initialize the 'dls_size' and 'dls_cnt' fields in the newly
198              allocated buffer. */
199
200           if (dlinfo(handle, RTLD_DI_SERINFOSIZE, sip) == -1) {
201               fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\n", dlerror());
202               exit(EXIT_FAILURE);
203           }
204
205           /* Fetch and print library search list. */
206
207           if (dlinfo(handle, RTLD_DI_SERINFO, sip) == -1) {
208               fprintf(stderr, "RTLD_DI_SERINFO failed: %s\n", dlerror());
209               exit(EXIT_FAILURE);
210           }
211
212           for (size_t j = 0; j < serinfo.dls_cnt; j++)
213               printf("dls_serpath[%zu].dls_name = %s\n",
214                      j, sip->dls_serpath[j].dls_name);
215
216           exit(EXIT_SUCCESS);
217       }
218

SEE ALSO

220       dl_iterate_phdr(3),   dladdr(3),   dlerror(3),   dlopen(3),   dlsym(3),
221       ld.so(8)
222
223
224
225Linux man-pages 6.04              2023-03-30                         dlinfo(3)
Impressum