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 19, 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_addr;    /* Load Offset 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 .Ed
 114 .Bl -tag -width ".Va l_addr"
 115 .It Va l_addr
 116 The load offset of the object, that is, the difference between
 117 the actual load address and the base virtual address the object
 118 was linked at.
 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 .El
 134 .It Dv RTLD_DI_SERINFO
 135 Retrieve the library search paths associated with the given
 136 .Fa handle
 137 argument.
 138 The
 139 .Fa p
 140 argument should point to
 141 .Vt Dl_serinfo
 142 structure buffer
 143 .Pq Fa "Dl_serinfo *p" .
 144 The
 145 .Vt Dl_serinfo
 146 structure must be initialized first with the
 147 .Dv RTLD_DI_SERINFOSIZE
 148 request.
 149 .Pp
 150 The returned
 151 .Vt Dl_serinfo
 152 structure contains
 153 .Va dls_cnt
 154 .Vt Dl_serpath
 155 entries.
 156 Each entry's
 157 .Va dlp_name
 158 field points to the search path.
 159 The corresponding
 160 .Va dlp_info
 161 field contains one of more flags indicating the origin of the path (see the
 162 .Dv LA_SER_*
 163 flags defined in the
 164 .In link.h
 165 header file).
 166 See
 167 .Sx EXAMPLES ,
 168 example 2, for a usage example.
 169 .It Dv RTLD_DI_SERINFOSIZE
 170 Initialize a
 171 .Vt Dl_serinfo
 172 structure for use in a
 173 .Dv RTLD_DI_SERINFO
 174 request.
 175 Both the
 176 .Va dls_cnt
 177 and
 178 .Va dls_size
 179 fields are returned to indicate the number of search paths applicable
 180 to the handle, and the total size of a
 181 .Vt Dl_serinfo
 182 buffer required to hold
 183 .Va dls_cnt
 184 .Vt Dl_serpath
 185 entries and the associated search path strings.
 186 See
 187 .Sx EXAMPLES ,
 188 example 2, for a usage example.
 189 .It Va RTLD_DI_ORIGIN
 190 Retrieve the origin of the dynamic object associated with the handle.
 191 On successful return,
 192 .Fa p
 193 argument is filled with the
 194 .Vt char
 195 pointer
 196 .Pq Fa "char *p" .
 197 .El
 198 .Sh RETURN VALUES
 199 The
 200 .Fn dlinfo
 201 function returns 0 on success, or \-1 if an error occurred.
 202 Whenever an error has been detected, a message detailing it can
 203 be retrieved via a call to
 204 .Xr dlerror 3 .
 205 .Sh EXAMPLES
 206 Example 1: Using
 207 .Fn dlinfo
 208 to retrieve
 209 .Vt Link_map
 210 structure.
 211 .Pp
 212 The following example shows how dynamic library can detect the list
 213 of shared libraries loaded after caller's one.
 214 For simplicity, error checking has been omitted.
 215 .Bd -literal -offset indent
 216 Link_map *map;
 217
 218 dlinfo(RTLD_SELF, RTLD_DI_LINKMAP, &map);
 219
 220 while (map != NULL) {
 221         printf("%p: %s\\n", map->l_addr, map->l_name);
 222         map = map->l_next;
 223 }
 224 .Ed
 225 .Pp
 226 Example 2: Using
 227 .Fn dlinfo
 228 to retrieve the library search paths.
 229 .Pp
 230 The following example shows how a dynamic object can inspect the library
 231 search paths that would be used to locate a simple filename with
 232 .Xr dlopen 3 .
 233 For simplicity, error checking has been omitted.
 234 .Bd -literal -offset indent
 235 Dl_serinfo       _info, *info = &_info;
 236 Dl_serpath      *path;
 237 unsigned int     cnt;
 238
 239 /* determine search path count and required buffer size */
 240 dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, (void *)info);
 241
 242 /* allocate new buffer and initialize */
 243 info = malloc(_info.dls_size);
 244 info->dls_size = _info.dls_size;
 245 info->dls_cnt = _info.dls_cnt;
 246
 247 /* obtain sarch path information */
 248 dlinfo(RTLD_SELF, RTLD_DI_SERINFO, (void *)info);
 249
 250 path = &info->dls_serpath[0];
 251
 252 for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) {
 253         (void) printf("%2d: %s\\n", cnt, path->dls_name);
 254 }
 255 .Ed
 256 .Sh SEE ALSO
 257 .Xr rtld 1 ,
 258 .Xr dladdr 3 ,
 259 .Xr dlopen 3 ,
 260 .Xr dlsym 3
 261 .Sh HISTORY
 262 The
 263 .Fn dlinfo
 264 function first appeared in the Solaris operating system.
 265 In
 266 .Fx ,
 267 it first appeared in
 268 .Fx 4.8 .
 269 .Sh AUTHORS
 270 .An -nosplit
 271 The
 272 .Fx
 273 implementation of the
 274 .Fn dlinfo
 275 function was originally written by
 276 .An Alexey Zelkin Aq Mt phantom@FreeBSD.org
 277 and later extended and improved by
 278 .An Alexander Kabaev Aq Mt kan@FreeBSD.org .
 279 .Pp
 280 The manual page for this function was written by
 281 .An Alexey Zelkin Aq Mt phantom@FreeBSD.org .