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