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