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