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