man3/dlinfo.3

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