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