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