man3/dlinfo.3

   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)
  47 or
  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 */
  94
  95     /* Plus additional fields private to the
  96        implementation */
  97 };
  98 .EE
  99 .in
 100 .TP
 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 .
 106 .TP
 107 .BR RTLD_DI_SERINFO " (\fIDl_serinfo *\fP)"
 108 Obtain the library search paths for the shared object referred to by
 109 .IR handle .
 110 The
 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.
 119 The
 120 .B RTLD_DI_SERINFOSIZE
 121 request described below allows applications to size the buffer suitably.
 122 The caller must perform the following steps:
 123 .RS
 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
 144 and
 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.
 151 .RE
 152 .IP
 153 The
 154 .I Dl_serinfo
 155 structure is defined as follows:
 156 .IP
 157 .in +4n
 158 .EX
 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;
 167 .EE
 168 .in
 169 .IP
 170 Each of the
 171 .I dls_serpath
 172 elements in the above structure is a structure of the following form:
 173 .IP
 174 .in +4n
 175 .EX
 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;
 182 .EE
 183 .in
 184 .IP
 185 The
 186 .I dls_flags
 187 field is currently unused, and always contains zero.
 188 .TP
 189 .BR RTLD_DI_SERINFOSIZE " (\fIDl_serinfo *\fP)"
 190 Populate the
 191 .I dls_size
 192 and
 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.
 201 .TP
 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 .
 207 .TP
 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
 228 .nh
 229 .TS
 230 allbox;
 231 lbx lb lb
 232 l l l.
 233 Interface       Attribute       Value
 234 T{
 235 .BR dlinfo ()
 236 T}      Thread safety   MT-Safe
 237 .TE
 238 .hy
 239 .ad
 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
 253 and
 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:
 257 .PP
 258 .in +4n
 259 .EX
 260 $ \fB./a.out /lib64/libm.so.6\fP
 261 dls_serpath[0].dls_name = /lib64
 262 dls_serpath[1].dls_name = /usr/lib64
 263 .EE
 264 .in
 265 .SS Program source
 266 \&
 267 .EX
 268 #define _GNU_SOURCE
 269 #include <dlfcn.h>
 270 #include <link.h>
 271 #include <stdio.h>
 272 #include <stdlib.h>
 273
 274 int
 275 main(int argc, char *argv[])
 276 {
 277     void *handle;
 278     Dl_serinfo serinfo;
 279     Dl_serinfo *sip;
 280
 281     if (argc != 2) {
 282         fprintf(stderr, "Usage: %s <libpath>\en", argv[0]);
 283         exit(EXIT_FAILURE);
 284     }
 285
 286     /* Obtain a handle for shared object specified on command line. */
 287
 288     handle = dlopen(argv[1], RTLD_NOW);
 289     if (handle == NULL) {
 290         fprintf(stderr, "dlopen() failed: %s\en", dlerror());
 291         exit(EXIT_FAILURE);
 292     }
 293
 294     /* Discover the size of the buffer that we must pass to
 295        RTLD_DI_SERINFO. */
 296
 297     if (dlinfo(handle, RTLD_DI_SERINFOSIZE, &serinfo) == \-1) {
 298         fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\en", dlerror());
 299         exit(EXIT_FAILURE);
 300     }
 301
 302     /* Allocate the buffer for use with RTLD_DI_SERINFO. */
 303
 304     sip = malloc(serinfo.dls_size);
 305     if (sip == NULL) {
 306         perror("malloc");
 307         exit(EXIT_FAILURE);
 308     }
 309
 310     /* Initialize the \(aqdls_size\(aq and \(aqdls_cnt\(aq fields in the newly
 311        allocated buffer. */
 312
 313     if (dlinfo(handle, RTLD_DI_SERINFOSIZE, sip) == \-1) {
 314         fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\en", dlerror());
 315         exit(EXIT_FAILURE);
 316     }
 317
 318     /* Fetch and print library search list. */
 319
 320     if (dlinfo(handle, RTLD_DI_SERINFO, sip) == \-1) {
 321         fprintf(stderr, "RTLD_DI_SERINFO failed: %s\en", dlerror());
 322         exit(EXIT_FAILURE);
 323     }
 324
 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);
 328
 329     exit(EXIT_SUCCESS);
 330 }
 331 .EE
 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)