xref: /dragonfly/lib/libc/gen/dlinfo.3 (revision 956939d5) 
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
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 Dv 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
88structures are maintained as double-linked list by
89.Xr rtld 1
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
101structure is defined in
102.In link.h
103and 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
113The base address of the object loaded into memory.
114.It l_name
115The full name of loaded shared object.
116.It l_ld
117The address of dynamic linking information segment
118.Dv ( PT_DYNAMIC )
119loaded into memory.
120.It l_next
121The next Link_map structure on the link-map list.
122.It l_prev
123The previous Link_map structure on the link-map list.
124.El
125.It Dv RTLD_DI_SERINFO
126Retrieve the library search paths associated with given
127.Fa handle
128argument.
129The
130.Fa p
131argument should point to
132.Ft Dl_serinfo
133structure buffer
134.Fa ( Dl_serinfo *p ) .
135.Ft Dl_serinfo
136structure must be initialized first with a
137.Dv RTLD_DI_SERINFOSIZE
138request.
139.Pp
140The returned
141.Ft Dl_serinfo
142structure contains
143.Fa dls_cnt
144.Ft Dl_serpath
145entries.
146Each entry's
147.Fa dlp_name
148field points to the search path.
149The corresponding
150.Fa dlp_info
151field contains one of more flags indicating the origin of the path (see the
152.Dv LA_SER_*
153flags defined in the
154.In link.h
155header file.)
156See
157.Sx EXAMPLES
158(Example 2) for usage example.
159.It Dv RTLD_DI_SERINFOSIZE
160Initialize a
161.Ft Dl_serinfo
162structure for use in a
163.Dv RTLD_DI_SERINFO
164request.
165Both the
166.Fa dls_cnt
167and
168.Fa dls_size
169fields are returned to indicate the number of search paths applicable
170to the handle, and the total size of a
171.Ft Dl_serinfo
172buffer required to hold
173.Fa dls_cnt
174.Ft Dl_serpath
175entries and the associated search path strings.
176See
177.Sx EXAMPLES
178(Example 2) for usage example.
179.It Dv RTLD_DI_ORIGIN
180Retrieve the origin of the dynamic object associated with the handle.
181On successful return
182.Fa p
183argument is filled with
184.Ft char
185pointer
186.Ft ( char *p ) .
187.El
188.Sh RETURN VALUES
189.Fn dlinfo
190returns 0 on success, or -1 if error occurred.
191Whenever an error has been detected, a message detailing it can
192be retrieved via a call to
193.Fn dlerror .
194.Sh EXAMPLES
195Example 1: Using
196.Fn dlinfo
197to retrieve Link_map structure.
198.Pp
199The following example shows how dynamic library can detect the list
200of shared libraries loaded after caller's one.
201For 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
213Example 2: Using
214.Fn dlinfo
215to retrieve the library search paths.
216.Pp
217The following example shows how a dynamic object can inspect the library
218search paths that would be used to locate a simple filename with
219.Fn dlopen .
220For 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
249The
250.Fn dlinfo
251function first appeared in the Solaris operating system.
252In
253.Fx
254it first appeared in
255.Fx 4.8 .
256.Sh AUTHORS
257.An -nosplit
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 .
272