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