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