Commit | Line | Data |
---|---|---|
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 | .\" | |
fcf53d9b | 26 | .\" $FreeBSD: head/lib/libc/gen/dlinfo.3 206622 2010-04-14 19:08:06Z uqs $ |
984263bc | 27 | .\" |
bb5b9bec | 28 | .Dd February 22, 2018 |
984263bc | 29 | .Dt DLINFO 3 |
fcf53d9b | 30 | .Os |
984263bc MD |
31 | .Sh NAME |
32 | .Nm dlinfo | |
33 | .Nd information about dynamically loaded object | |
34 | .Sh LIBRARY | |
9f488f94 SW |
35 | This function is not in a library. |
36 | It is included in every dynamically linked program automatically. | |
984263bc MD |
37 | .Sh SYNOPSIS |
38 | .In link.h | |
39 | .In dlfcn.h | |
40 | .Ft int | |
bb5b9bec | 41 | .Fn dlinfo "void * restrict handle" "int request" "void * restrict p" |
984263bc MD |
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 | |
fcf53d9b | 54 | The |
984263bc | 55 | .Fa handle |
fcf53d9b JM |
56 | argument is either the value returned from the |
57 | .Xr dlopen 3 | |
984263bc MD |
58 | function call or special handle |
59 | .Dv RTLD_SELF . | |
fcf53d9b JM |
60 | If |
61 | .Fa handle | |
62 | is the value returned from | |
63 | .Xr dlopen 3 , | |
64 | the information returned by the | |
984263bc | 65 | .Fn dlinfo |
fcf53d9b | 66 | function pertains to the specified object. |
984263bc MD |
67 | If handle is the special handle |
68 | .Dv RTLD_SELF , | |
69 | the information returned pertains to the caller itself. | |
70 | .Pp | |
fcf53d9b | 71 | Possible values for the |
984263bc | 72 | .Fa request |
fcf53d9b JM |
73 | argument are: |
74 | .Bl -tag -width indent | |
d9c39f74 | 75 | .It Dv RTLD_DI_LINKMAP |
fcf53d9b JM |
76 | Retrieve the |
77 | .Vt Link_map | |
78 | .Pq Vt "struct link_map" | |
79 | structure pointer for the specified | |
80 | .Fa handle . | |
81 | On successful return, the | |
984263bc | 82 | .Fa p |
fcf53d9b JM |
83 | argument is filled with the pointer to the |
84 | .Vt Link_map | |
85 | structure | |
86 | .Pq Fa "Link_map **p" | |
87 | describing a shared object specified by the | |
984263bc MD |
88 | .Fa handle |
89 | argument. | |
fcf53d9b JM |
90 | The |
91 | .Vt Link_map | |
92 | structures are maintained as a doubly linked list by | |
9f488f94 | 93 | .Xr ld-elf.so.2 1 , |
fcf53d9b JM |
94 | in the same order as |
95 | .Xr dlopen 3 | |
984263bc | 96 | and |
fcf53d9b | 97 | .Xr dlclose 3 |
984263bc MD |
98 | are called. |
99 | See | |
fcf53d9b JM |
100 | .Sx EXAMPLES , |
101 | example 1. | |
984263bc MD |
102 | .Pp |
103 | The | |
fcf53d9b | 104 | .Vt Link_map |
44cb301e SW |
105 | structure is defined in |
106 | .In link.h | |
107 | and has the following members: | |
fcf53d9b JM |
108 | .Bd -literal -offset indent |
109 | caddr_t l_addr; /* Base Address of library */ | |
110 | const char *l_name; /* Absolute Path to Library */ | |
111 | const void *l_ld; /* Pointer to .dynamic in memory */ | |
112 | struct link_map *l_next, /* linked list of mapped libs */ | |
1bf4b486 | 113 | *l_prev; |
984263bc | 114 | .Ed |
fcf53d9b JM |
115 | .Bl -tag -width ".Va l_addr" |
116 | .It Va l_addr | |
984263bc | 117 | The base address of the object loaded into memory. |
fcf53d9b JM |
118 | .It Va l_name |
119 | The full name of the loaded shared object. | |
120 | .It Va l_ld | |
121 | The address of the dynamic linking information segment | |
122 | .Pq Dv PT_DYNAMIC | |
984263bc | 123 | loaded into memory. |
fcf53d9b JM |
124 | .It Va l_next |
125 | The next | |
126 | .Vt Link_map | |
127 | structure on the link-map list. | |
128 | .It Va l_prev | |
129 | The previous | |
130 | .Vt Link_map | |
131 | structure on the link-map list. | |
984263bc | 132 | .El |
d9c39f74 | 133 | .It Dv RTLD_DI_SERINFO |
fcf53d9b | 134 | Retrieve the library search paths associated with the given |
984263bc MD |
135 | .Fa handle |
136 | argument. | |
137 | The | |
138 | .Fa p | |
139 | argument should point to | |
fcf53d9b | 140 | .Vt Dl_serinfo |
984263bc | 141 | structure buffer |
fcf53d9b JM |
142 | .Pq Fa "Dl_serinfo *p" . |
143 | The | |
144 | .Vt Dl_serinfo | |
145 | structure must be initialized first with the | |
984263bc MD |
146 | .Dv RTLD_DI_SERINFOSIZE |
147 | request. | |
148 | .Pp | |
149 | The returned | |
fcf53d9b | 150 | .Vt Dl_serinfo |
984263bc | 151 | structure contains |
fcf53d9b JM |
152 | .Va dls_cnt |
153 | .Vt Dl_serpath | |
984263bc MD |
154 | entries. |
155 | Each entry's | |
fcf53d9b | 156 | .Va dlp_name |
984263bc MD |
157 | field points to the search path. |
158 | The corresponding | |
fcf53d9b | 159 | .Va dlp_info |
984263bc MD |
160 | field contains one of more flags indicating the origin of the path (see the |
161 | .Dv LA_SER_* | |
44cb301e SW |
162 | flags defined in the |
163 | .In link.h | |
fcf53d9b | 164 | header file). |
984263bc | 165 | See |
fcf53d9b JM |
166 | .Sx EXAMPLES , |
167 | example 2, for a usage example. | |
d9c39f74 | 168 | .It Dv RTLD_DI_SERINFOSIZE |
984263bc | 169 | Initialize a |
fcf53d9b | 170 | .Vt Dl_serinfo |
984263bc MD |
171 | structure for use in a |
172 | .Dv RTLD_DI_SERINFO | |
173 | request. | |
174 | Both the | |
fcf53d9b | 175 | .Va dls_cnt |
984263bc | 176 | and |
fcf53d9b | 177 | .Va dls_size |
984263bc MD |
178 | fields are returned to indicate the number of search paths applicable |
179 | to the handle, and the total size of a | |
fcf53d9b | 180 | .Vt Dl_serinfo |
984263bc | 181 | buffer required to hold |
fcf53d9b JM |
182 | .Va dls_cnt |
183 | .Vt Dl_serpath | |
984263bc MD |
184 | entries and the associated search path strings. |
185 | See | |
fcf53d9b JM |
186 | .Sx EXAMPLES , |
187 | example 2, for a usage example. | |
188 | .It Va RTLD_DI_ORIGIN | |
984263bc | 189 | Retrieve the origin of the dynamic object associated with the handle. |
fcf53d9b | 190 | On successful return, |
984263bc | 191 | .Fa p |
fcf53d9b JM |
192 | argument is filled with the |
193 | .Vt char | |
984263bc | 194 | pointer |
fcf53d9b | 195 | .Pq Fa "char *p" . |
984263bc | 196 | .El |
0b84df5c | 197 | .Sh RETURN VALUES |
fcf53d9b | 198 | The |
0b84df5c | 199 | .Fn dlinfo |
fcf53d9b | 200 | function returns 0 on success, or \-1 if an error occurred. |
0b84df5c SW |
201 | Whenever an error has been detected, a message detailing it can |
202 | be retrieved via a call to | |
fcf53d9b | 203 | .Xr dlerror 3 . |
984263bc MD |
204 | .Sh EXAMPLES |
205 | Example 1: Using | |
206 | .Fn dlinfo | |
fcf53d9b JM |
207 | to retrieve |
208 | .Vt Link_map | |
209 | structure. | |
984263bc MD |
210 | .Pp |
211 | The following example shows how dynamic library can detect the list | |
212 | of shared libraries loaded after caller's one. | |
213 | For simplicity, error checking has been omitted. | |
fcf53d9b JM |
214 | .Bd -literal -offset indent |
215 | Link_map *map; | |
984263bc | 216 | |
fcf53d9b | 217 | dlinfo(RTLD_SELF, RTLD_DI_LINKMAP, &map); |
984263bc | 218 | |
fcf53d9b JM |
219 | while (map != NULL) { |
220 | printf("%p: %s\\n", map->l_addr, map->l_name); | |
984263bc | 221 | map = map->l_next; |
fcf53d9b | 222 | } |
984263bc MD |
223 | .Ed |
224 | .Pp | |
225 | Example 2: Using | |
226 | .Fn dlinfo | |
227 | to retrieve the library search paths. | |
228 | .Pp | |
229 | The following example shows how a dynamic object can inspect the library | |
230 | search paths that would be used to locate a simple filename with | |
fcf53d9b | 231 | .Xr dlopen 3 . |
984263bc | 232 | For simplicity, error checking has been omitted. |
fcf53d9b JM |
233 | .Bd -literal -offset indent |
234 | Dl_serinfo _info, *info = &_info; | |
235 | Dl_serpath *path; | |
236 | unsigned int cnt; | |
984263bc | 237 | |
fcf53d9b JM |
238 | /* determine search path count and required buffer size */ |
239 | dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, (void *)info); | |
984263bc | 240 | |
fcf53d9b JM |
241 | /* allocate new buffer and initialize */ |
242 | info = malloc(_info.dls_size); | |
243 | info->dls_size = _info.dls_size; | |
244 | info->dls_cnt = _info.dls_cnt; | |
984263bc | 245 | |
fcf53d9b JM |
246 | /* obtain sarch path information */ |
247 | dlinfo(RTLD_SELF, RTLD_DI_SERINFO, (void *)info); | |
984263bc | 248 | |
fcf53d9b | 249 | path = &info->dls_serpath[0]; |
984263bc | 250 | |
fcf53d9b JM |
251 | for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) { |
252 | (void) printf("%2d: %s\\n", cnt, path->dls_name); | |
253 | } | |
984263bc | 254 | .Ed |
984263bc MD |
255 | .Sh SEE ALSO |
256 | .Xr rtld 1 , | |
fcf53d9b | 257 | .Xr dlfcn 3 |
984263bc MD |
258 | .Sh HISTORY |
259 | The | |
260 | .Fn dlinfo | |
261 | function first appeared in the Solaris operating system. | |
262 | In | |
fcf53d9b | 263 | .Fx , |
984263bc MD |
264 | it first appeared in |
265 | .Fx 4.8 . | |
266 | .Sh AUTHORS | |
f8a0f69a | 267 | .An -nosplit |
984263bc MD |
268 | The |
269 | .Fx | |
fcf53d9b | 270 | implementation of the |
984263bc MD |
271 | .Fn dlinfo |
272 | function was originally written by | |
98b3d9ad | 273 | .An Alexey Zelkin Aq Mt phantom@FreeBSD.org |
984263bc | 274 | and later extended and improved by |
98b3d9ad | 275 | .An Alexander Kabaev Aq Mt kan@FreeBSD.org . |
984263bc MD |
276 | .Pp |
277 | The manual page for this function was written by | |
98b3d9ad | 278 | .An Alexey Zelkin Aq Mt phantom@FreeBSD.org . |