2 .\" Copyright (c) 2003 Alexey Zelkin <phantom@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
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 $
34 .Nd information about dynamically loaded object
41 .Fn dlinfo "void * __restrict handle" "int request" "void * __restrict p"
45 function provides information about dynamically loaded object.
48 and exact meaning and type of
50 argument depend on value of the
52 argument provided by caller.
56 argument is either the value returned from a
58 function call or special handle
60 If handle is the value returned from
62 call, the information returned by the
64 function is pertains the specified object.
65 If handle is the special handle
67 the information returned pertains to the caller itself.
69 The following are possible values for
71 argument to be passed into
74 .It Dv RTLD_DI_LINKMAP
75 Retrieve the Link_map (or
80 On successful return the
82 argument is filled with pointer to Link_map structure
84 describing shared object specified by
88 structures are maintained as double-linked list by
101 structure is defined in
103 and has the following members:
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 */
113 The base address of the object loaded into memory.
115 The full name of loaded shared object.
117 The address of dynamic linking information segment
121 The next Link_map structure on the link-map list.
123 The previous Link_map structure on the link-map list.
125 .It Dv RTLD_DI_SERINFO
126 Retrieve the library search paths associated with given
131 argument should point to
134 .Fa ( Dl_serinfo *p ) .
136 structure must be initialized first with a
137 .Dv RTLD_DI_SERINFOSIZE
148 field points to the search path.
151 field contains one of more flags indicating the origin of the path (see the
158 (Example 2) for usage example.
159 .It Dv RTLD_DI_SERINFOSIZE
162 structure for use in a
169 fields are returned to indicate the number of search paths applicable
170 to the handle, and the total size of a
172 buffer required to hold
175 entries and the associated search path strings.
178 (Example 2) for usage example.
179 .It Dv RTLD_DI_ORIGIN
180 Retrieve the origin of the dynamic object associated with the handle.
183 argument is filled with
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
197 to retrieve Link_map structure.
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.
205 dlinfo(RTLD_SELF, RTLD_DI_LINKMAP, &map);
207 while (map != NULL) {
208 printf("%p: %s\en", map->l_addr, map->l_name);
215 to retrieve the library search paths.
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
220 For simplicity, error checking has been omitted.
222 Dl_serinfo _info, *info = &_info;
226 /* determine search path count and required buffer size */
227 dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, (void *)info);
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;
234 /* obtain sarch path information */
235 dlinfo(RTLD_SELF, RTLD_DI_SERINFO, (void *)info);
237 path = &info->dls_serpath[0];
239 for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) {
240 (void) printf("%2d: %s\en", cnt, path->dls_name);
251 function first appeared in the Solaris operating system.
262 function was originally written by
264 .Aq phantom@FreeBSD.org
265 and later extended and improved by
267 .Aq kan@FreeBSD.org .
269 The manual page for this function was written by
271 .Aq phantom@FreeBSD.org .