lib/libc/gen/dlinfo.3

   1 .\"
   2 .\" Copyright (c) 2003 Alexey Zelkin <phantom@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd May 21, 2020
  27 .Dt DLINFO 3
  28 .Os
  29 .Sh NAME
  30 .Nm dlinfo
  31 .Nd information about dynamically loaded object
  32 .Sh LIBRARY
  33 .Lb libc
  34 .Sh SYNOPSIS
  35 .In link.h
  36 .In dlfcn.h
  37 .Ft int
  38 .Fn dlinfo "void * restrict handle" "int request" "void * restrict p"
  39 .Sh DESCRIPTION
  40 The
  41 .Fn dlinfo
  42 function provides information about dynamically loaded object.
  43 The action taken by
  44 .Fn dlinfo
  45 and exact meaning and type of
  46 .Fa p
  47 argument depend on value of the
  48 .Fa request
  49 argument provided by caller.
  50 .Pp
  51 The
  52 .Fa handle
  53 argument is either the value returned from the
  54 .Xr dlopen 3
  55 function call or special handle
  56 .Dv RTLD_SELF .
  57 If
  58 .Fa handle
  59 is the value returned from
  60 .Xr dlopen 3 ,
  61 the information returned by the
  62 .Fn dlinfo
  63 function pertains to the specified object.
  64 If handle is the special handle
  65 .Dv RTLD_SELF ,
  66 the information returned pertains to the caller itself.
  67 .Pp
  68 Possible values for the
  69 .Fa request
  70 argument are:
  71 .Bl -tag -width indent
  72 .It Dv RTLD_DI_LINKMAP
  73 Retrieve the
  74 .Vt Link_map
  75 .Pq Vt "struct link_map"
  76 structure pointer for the specified
  77 .Fa handle .
  78 On successful return, the
  79 .Fa p
  80 argument is filled with the pointer to the
  81 .Vt Link_map
  82 structure
  83 .Pq Fa "Link_map **p"
  84 describing a shared object specified by the
  85 .Fa handle
  86 argument.
  87 The
  88 .Vt Link_map
  89 structures are maintained as a doubly linked list by
  90 .Xr ld.so 1 ,
  91 in the same order as
  92 .Xr dlopen 3
  93 and
  94 .Xr dlclose 3
  95 are called.
  96 See
  97 .Sx EXAMPLES ,
  98 example 1.
  99 .Pp
 100 The
 101 .Vt Link_map
 102 structure is defined in
 103 .In link.h
 104 and has the following members:
 105 .Bd -literal -offset indent
 106 caddr_t         l_base;    /* Base Address of library */
 107 const char      *l_name;   /* Absolute Path to Library */
 108 const void      *l_ld;     /* Pointer to .dynamic in memory */
 109 struct link_map *l_next,   /* linked list of mapped libs */
 110                 *l_prev;
 111 caddr_t         l_addr;     /* Load Offset of library */
 112 const char      *l_refname; /* Object this one filters for */
 113 .Ed
 114 .Bl -tag -width ".Va l_addr"
 115 .It Va l_base
 116 The base address of the object loaded into memory.
 117 .It Va l_name
 118 The full name of the loaded shared object.
 119 .It Va l_ld
 120 The address of the dynamic linking information segment
 121 .Pq Dv PT_DYNAMIC
 122 loaded into memory.
 123 .It Va l_next
 124 The next
 125 .Vt Link_map
 126 structure on the link-map list.
 127 .It Va l_prev
 128 The previous
 129 .Vt Link_map
 130 structure on the link-map list.
 131 .It Va l_addr
 132 The load offset of the object, that is, the difference between
 133 the actual load address and the base virtual address the object
 134 was linked at.
 135 .It Va l_refname
 136 A name of the object this object filters for, if any.
 137 If there are more then one filtee, a name from the first
 138 .Dv DT_FILTER
 139 dynamic entry is supplied.
 140 .El
 141 .It Dv RTLD_DI_SERINFO
 142 Retrieve the library search paths associated with the given
 143 .Fa handle
 144 argument.
 145 The
 146 .Fa p
 147 argument should point to
 148 .Vt Dl_serinfo
 149 structure buffer
 150 .Pq Fa "Dl_serinfo *p" .
 151 The
 152 .Vt Dl_serinfo
 153 structure must be initialized first with the
 154 .Dv RTLD_DI_SERINFOSIZE
 155 request.
 156 .Pp
 157 The returned
 158 .Vt Dl_serinfo
 159 structure contains
 160 .Va dls_cnt
 161 .Vt Dl_serpath
 162 entries.
 163 Each entry's
 164 .Va dlp_name
 165 field points to the search path.
 166 The corresponding
 167 .Va dlp_info
 168 field contains one of more flags indicating the origin of the path (see the
 169 .Dv LA_SER_*
 170 flags defined in the
 171 .In link.h
 172 header file).
 173 See
 174 .Sx EXAMPLES ,
 175 example 2, for a usage example.
 176 .It Dv RTLD_DI_SERINFOSIZE
 177 Initialize a
 178 .Vt Dl_serinfo
 179 structure for use in a
 180 .Dv RTLD_DI_SERINFO
 181 request.
 182 Both the
 183 .Va dls_cnt
 184 and
 185 .Va dls_size
 186 fields are returned to indicate the number of search paths applicable
 187 to the handle, and the total size of a
 188 .Vt Dl_serinfo
 189 buffer required to hold
 190 .Va dls_cnt
 191 .Vt Dl_serpath
 192 entries and the associated search path strings.
 193 See
 194 .Sx EXAMPLES ,
 195 example 2, for a usage example.
 196 .It Va RTLD_DI_ORIGIN
 197 Retrieve the origin of the dynamic object associated with the handle.
 198 On successful return,
 199 .Fa p
 200 argument is filled with the
 201 .Vt char
 202 pointer
 203 .Pq Fa "char *p" .
 204 .El
 205 .Sh RETURN VALUES
 206 The
 207 .Fn dlinfo
 208 function returns 0 on success, or \-1 if an error occurred.
 209 Whenever an error has been detected, a message detailing it can
 210 be retrieved via a call to
 211 .Xr dlerror 3 .
 212 .Sh EXAMPLES
 213 Example 1: Using
 214 .Fn dlinfo
 215 to retrieve
 216 .Vt Link_map
 217 structure.
 218 .Pp
 219 The following example shows how dynamic library can detect the list
 220 of shared libraries loaded after caller's one.
 221 For simplicity, error checking has been omitted.
 222 .Bd -literal -offset indent
 223 Link_map *map;
 224
 225 dlinfo(RTLD_SELF, RTLD_DI_LINKMAP, &map);
 226
 227 while (map != NULL) {
 228         printf("%p: %s\\n", map->l_addr, map->l_name);
 229         map = map->l_next;
 230 }
 231 .Ed
 232 .Pp
 233 Example 2: Using
 234 .Fn dlinfo
 235 to retrieve the library search paths.
 236 .Pp
 237 The following example shows how a dynamic object can inspect the library
 238 search paths that would be used to locate a simple filename with
 239 .Xr dlopen 3 .
 240 For simplicity, error checking has been omitted.
 241 .Bd -literal -offset indent
 242 Dl_serinfo       _info, *info = &_info;
 243 Dl_serpath      *path;
 244 unsigned int     cnt;
 245
 246 /* determine search path count and required buffer size */
 247 dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, (void *)info);
 248
 249 /* allocate new buffer and initialize */
 250 info = malloc(_info.dls_size);
 251 info->dls_size = _info.dls_size;
 252 info->dls_cnt = _info.dls_cnt;
 253
 254 /* obtain sarch path information */
 255 dlinfo(RTLD_SELF, RTLD_DI_SERINFO, (void *)info);
 256
 257 path = &info->dls_serpath[0];
 258
 259 for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) {
 260         (void) printf("%2d: %s\\n", cnt, path->dls_name);
 261 }
 262 .Ed
 263 .Sh SEE ALSO
 264 .Xr rtld 1 ,
 265 .Xr dladdr 3 ,
 266 .Xr dlopen 3 ,
 267 .Xr dlsym 3
 268 .Sh HISTORY
 269 The
 270 .Fn dlinfo
 271 function first appeared in the Solaris operating system.
 272 In
 273 .Fx ,
 274 it first appeared in
 275 .Fx 4.8 .
 276 .Sh AUTHORS
 277 .An -nosplit
 278 The
 279 .Fx
 280 implementation of the
 281 .Fn dlinfo
 282 function was originally written by
 283 .An Alexey Zelkin Aq Mt phantom@FreeBSD.org
 284 and later extended and improved by
 285 .An Alexander Kabaev Aq Mt kan@FreeBSD.org .
 286 .Pp
 287 The manual page for this function was written by
 288 .An Alexey Zelkin Aq Mt phantom@FreeBSD.org .