- Uniformly use .In for header file references.
[dragonfly.git] / lib / libc / gen / dlinfo.3
CommitLineData
984263bc
MD
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 $
44cb301e 27.\" $DragonFly: src/lib/libc/gen/dlinfo.3,v 1.6 2006/05/26 19:39:36 swildner Exp $
984263bc
MD
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
43The
44.Fn dlinfo
45function provides information about dynamically loaded object.
46The action taken by
47.Fn dlinfo
48and exact meaning and type of
49.Fa p
50argument depend on value of the
51.Fa request
52argument provided by caller.
53.Pp
54A
55.Fa handle
56argument is either the value returned from a
57.Fn dlopen
58function call or special handle
59.Dv RTLD_SELF .
60If handle is the value returned from
61.Fn dlopen
62call, the information returned by the
63.Fn dlinfo
64function is pertains the specified object.
65If handle is the special handle
66.Dv RTLD_SELF ,
67the information returned pertains to the caller itself.
68.Pp
69The following are possible values for
70.Fa request
71argument to be passed into
72.Fn dlinfo :
73.Bl -tag -width Ds
74.It RTLD_DI_LINKMAP
75Retrieve the Link_map (or
76.Ft struct link_map )
77structure pointer for
78.Fa handle
79specified.
80On successful return the
81.Fa p
82argument is filled with pointer to Link_map structure
83.Ft ( Link_map **p )
84describing shared object specified by
85.Fa handle
86argument.
87.Ft Link_map
88stuctures are maintained as double-linked list by
1bf4b486 89.Xr ld.so 1
984263bc
MD
90in same order as
91.Fn dlopen
92and
93.Fn dlclose
94are called.
95See
96.Sx EXAMPLES
97(Example 1.)
98.Pp
99The
100.Ft Link_map
44cb301e
SW
101structure is defined in
102.In link.h
103and has the following members:
984263bc
MD
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 */
1bf4b486 110 *l_prev;
984263bc
MD
111.Ed
112.Bl -tag -width Ds
113.It l_addr
114The base address of the object loaded into memory.
115.It l_name
116The full name of loaded shared object.
117.It l_ld
118The address of dynamic linking information segment
119.Dv ( PT_DYNAMIC )
120loaded into memory.
121.It l_next
122The next Link_map structure on the link-map list.
123.It l_prev
124The previous Link_map structure on the link-map list.
125.El
126.It RTLD_DI_SERINFO
127Retrieve the library search paths associated with given
128.Fa handle
129argument.
130The
131.Fa p
132argument should point to
133.Ft Dl_serinfo
134structure buffer
135.Fa ( Dl_serinfo *p ) .
136.Ft Dl_serinfo
137structure must be initialized first with a
138.Dv RTLD_DI_SERINFOSIZE
139request.
140.Pp
141The returned
142.Ft Dl_serinfo
143structure contains
144.Dv dls_cnt
145.Ft Dl_serpath
146entries.
147Each entry's
148.Dv dlp_name
149field points to the search path.
150The corresponding
151.Dv dlp_info
152field contains one of more flags indicating the origin of the path (see the
153.Dv LA_SER_*
44cb301e
SW
154flags defined in the
155.In link.h
156header file.)
984263bc
MD
157See
158.Sx EXAMPLES
159(Example 2) for usage example.
160.It RTLD_DI_SERINFOSIZE
161Initialize a
162.Ft Dl_serinfo
163structure for use in a
164.Dv RTLD_DI_SERINFO
165request.
166Both the
167.Dv dls_cnt
168and
169.Dv dls_size
170fields are returned to indicate the number of search paths applicable
171to the handle, and the total size of a
172.Ft Dl_serinfo
173buffer required to hold
174.Dv dls_cnt
175.Ft Dl_serpath
176entries and the associated search path strings.
177See
178.Sx EXAMPLES
179(Example 2) for usage example.
180.It RTLD_DI_ORIGIN
181Retrieve the origin of the dynamic object associated with the handle.
182On successful return
183.Fa p
184argument is filled with
185.Ft char
186pointer
187.Ft ( char *p ) .
188.El
0b84df5c
SW
189.Sh RETURN VALUES
190.Fn dlinfo
191returns 0 on success, or -1 if error occured.
192Whenever an error has been detected, a message detailing it can
193be retrieved via a call to
194.Fn dlerror .
984263bc
MD
195.Sh EXAMPLES
196Example 1: Using
197.Fn dlinfo
198to retrieve Link_map structure.
199.Pp
200The following example shows how dynamic library can detect the list
201of shared libraries loaded after caller's one.
202For 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) {
a3220ac5 209 printf("%p: %s\en", map->l_addr, map->l_name);
984263bc
MD
210 map = map->l_next;
211 }
212.Ed
213.Pp
214Example 2: Using
215.Fn dlinfo
216to retrieve the library search paths.
217.Pp
218The following example shows how a dynamic object can inspect the library
219search paths that would be used to locate a simple filename with
220.Fn dlopen .
221For 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++) {
a3220ac5 241 (void) printf("%2d: %s\en", cnt, path->dls_name);
984263bc
MD
242 }
243.Ed
984263bc
MD
244.Sh SEE ALSO
245.Xr rtld 1 ,
246.Xr dladdr 3 ,
247.Xr dlopen 3 ,
248.Xr dlsym 3
249.Sh HISTORY
250The
251.Fn dlinfo
252function first appeared in the Solaris operating system.
253In
254.Fx
255it first appeared in
256.Fx 4.8 .
257.Sh AUTHORS
258The
259.Fx
260implementation of
261.Fn dlinfo
262function was originally written by
263.An Alexey Zelkin
264.Aq phantom@FreeBSD.org
265and later extended and improved by
266.An Alexander Kabaev
267.Aq kan@FreeBSD.org .
268.Pp
269The manual page for this function was written by
270.An Alexey Zelkin
271.Aq phantom@FreeBSD.org .