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