| blob | 9118e591b10561bbe75d0a0b8dd373b2f6a4bf76 |
1 '\" te
2 .\" Copyright (c) 2009, Sun Microsystems,
3 .\" Inc. All Rights Reserved.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH DLINFO 3C "Feb 4, 2009"
8 .SH NAME
9 dlinfo \- dynamic load information
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #include <dlfcn.h>
14 #include <link.h>
15 #include <limits.h>
16 #include <sys/mman.h>
18 \fBint\fR \fBdlinfo\fR(\fBvoid *\fR\fIhandle\fR, \fBint\fR \fIrequest\fR, \fBvoid *\fR\fIp\fR);
19 .fi
21 .SH DESCRIPTION
22 .sp
23 .LP
24 The \fBdlinfo()\fR function sets or extracts information from the runtime
25 linker \fBld.so.1\fR(1). This function is loosely modeled after the
26 \fBioctl\fR(2) function. The \fIrequest\fR argument and a third argument of
27 varying type are passed to \fBdlinfo()\fR. The action taken by \fBdlinfo()\fR
28 depends on the value of the \fIrequest\fR that is provided.
29 .sp
30 .LP
31 The \fIhandle\fR argument is either the value that is returned from a
32 \fBdlopen\fR(3C) or \fBdlmopen()\fR call, or the special handle
33 \fBRTLD_SELF\fR. A \fIhandle\fR argument is required for all requests except
34 \fBRTLD_DI_CONFIGADDR\fR, \fBRTLD_DI_GETSIGNAL\fR, and \fBRTLD_DI_SETSIGNAL\fR.
35 If \fIhandle\fR is the value that is returned from a \fBdlopen()\fR or
36 \fBdlmopen()\fR call, the information returned by the \fBdlinfo()\fR call
37 pertains to the specified object. If \fIhandle\fR is the special handle
38 \fBRTLD_SELF\fR, the information returned by the \fBdlinfo()\fR call pertains
39 to the caller.
40 .sp
41 .LP
42 The \fIrequest\fR argument can take the following values:
43 .sp
44 .ne 2
45 .na
46 \fB\fBRTLD_DI_ARGSINFO\fR\fR
47 .ad
48 .sp .6
49 .RS 4n
50 Obtain process argument information. The \fIp\fR argument is a pointer
51 (\fBDl_argsinfo_t *\fR\fIp\fR). The following elements from this structure are
52 initialized:
53 .sp
54 .ne 2
55 .na
56 \fB\fBdla_argc\fR\fR
57 .ad
58 .RS 12n
59 The number of arguments passed to the process.
60 .RE
62 .sp
63 .ne 2
64 .na
65 \fB\fBdla_argv\fR\fR
66 .ad
67 .RS 12n
68 The argument array passed to the process.
69 .RE
71 .sp
72 .ne 2
73 .na
74 \fB\fBdla_envp\fR\fR
75 .ad
76 .RS 12n
77 The active environment variable array that is available to the process. This
78 element initially points to the environment variable array that is made
79 available to \fBexec\fR(2). This element can be updated should an alternative
80 environment be established by the process. See \fBputenv\fR(3C).
81 .RE
83 .sp
84 .ne 2
85 .na
86 \fB\fBdla_auxv\fR\fR
87 .ad
88 .RS 12n
89 The auxiliary vector array passed to the process.
90 .RE
92 A process can be established from executing the runtime linker directly from
93 the command line. See \fBld.so.1\fR(1). The \fBDl_argsinfo_t\fR information
94 reflects the information that is made available to the application regardless
95 of how the runtime linker has been invoked.
96 .RE
98 .sp
99 .ne 2
100 .na
101 \fB\fBRTLD_DI_CONFIGADDR\fR\fR
102 .ad
103 .sp .6
104 .RS 4n
105 Obtain the configuration file information. The \fIp\fR argument is a
106 \fBDl_info_t\fR pointer (\fBDl_info_t *\fR\fIp\fR). The following elements from
107 this structure are initialized:
108 .sp
109 .ne 2
110 .na
111 \fB\fBdli_fname\fR\fR
112 .ad
113 .RS 13n
114 The full name of the configuration file.
115 .RE
117 .sp
118 .ne 2
119 .na
120 \fB\fBdli_fbase\fR\fR
121 .ad
122 .RS 13n
123 The base address of the configuration file loaded into memory.
124 .RE
126 .RE
128 .sp
129 .ne 2
130 .na
131 \fB\fBRTLD_DI_LINKMAP\fR\fR
132 .ad
133 .sp .6
134 .RS 4n
135 Obtain the \fBLink_map\fR for the \fIhandle\fR that is specified. The \fIp\fR
136 argument points to a \fBLink_map\fR pointer (\fBLink_map **\fR\fIp\fR). The
137 actual storage for the \fBLink_map\fR structure is maintained by \fBld.so.1\fR.
138 .sp
139 The \fBLink_map\fR structure includes the following members:
140 .sp
141 .in +2
142 .nf
143 unsigned long l_addr; /* base address */
144 char *l_name; /* object name */
145 Elf32_Dyn *l_ld; /* .dynamic section */
146 Link_map *l_next; /* next link object */
147 Link_map *l_prev; /* previous link object */
148 char *l_refname; /* filter reference name */
149 .fi
150 .in -2
152 .sp
153 .ne 2
154 .na
155 \fB\fBl_addr\fR\fR
156 .ad
157 .RS 13n
158 The base address of the object loaded into memory.
159 .RE
161 .sp
162 .ne 2
163 .na
164 \fB\fBl_name\fR\fR
165 .ad
166 .RS 13n
167 The full name of the loaded object. This full name is the filename of the
168 object as referenced by \fBld.so.1\fR.
169 .RE
171 .sp
172 .ne 2
173 .na
174 \fB\fBl_ld\fR\fR
175 .ad
176 .RS 13n
177 Points to the \fBSHT_DYNAMIC\fR structure.
178 .RE
180 .sp
181 .ne 2
182 .na
183 \fB\fBl_next\fR\fR
184 .ad
185 .RS 13n
186 The next \fBLink_map\fR on the link-map list. Other objects on the same
187 link-map list as the current object can be examined by following the
188 \fBl_next\fR and \fBl_prev\fR members.
189 .RE
191 .sp
192 .ne 2
193 .na
194 \fB\fBl_prev\fR\fR
195 .ad
196 .RS 13n
197 The previous \fBLink_map\fR on the link-map list.
198 .RE
200 .sp
201 .ne 2
202 .na
203 \fB\fBl_refname\fR\fR
204 .ad
205 .RS 13n
206 If the object that is referenced is a \fIfilter\fR, this member points to the
207 name of the object being filtered. If the object is not a \fIfilter\fR, this
208 member is \fB0\fR. See the \fILinker and Libraries Guide\fR.
209 .RE
211 .RE
213 .sp
214 .ne 2
215 .na
216 \fB\fBRTLD_DI_LMID\fR\fR
217 .ad
218 .sp .6
219 .RS 4n
220 Obtain the \fBID\fR for the link-map list upon which the \fIhandle\fR is
221 loaded. The \fIp\fR argument is a \fBLmid_t\fR pointer (\fBLmid_t *\fR\fIp\fR).
222 .RE
224 .sp
225 .ne 2
226 .na
227 \fB\fBRTLD_DI_MMAPCNT\fR\fR
228 .ad
229 .sp .6
230 .RS 4n
231 Determine the number of segment mappings for the \fIhandle\fR that is
232 specified, for use in a \fBRTLD_DI_MMAPS\fR request. The \fIp\fR argument is a
233 \fBuint_t\fR pointer (\fBuint_t *\fR\fIp\fR). On return from a
234 \fBRTLD_DI_MMAPCNT\fR request, the \fBuint_t\fR value that is pointed to by
235 \fIp\fR contains the number of segment mappings that the associated object
236 uses.
237 .sp
238 To obtain the complete mapping information for an object, a
239 \fBmmapobj_result_t\fR array for \fBRTLD_DI_MMAPCNT\fR entries must be
240 provided. This array is assigned to the \fBdlm_maps\fR member, and the number
241 of entries available in the arry are assigned to the \fBdlm_acnt\fR member.
242 This initialized structure is then passed to a \fBRTLD_DI_MMAPS\fR request. See
243 \fBEXAMPLES\fR.
244 .RE
246 .sp
247 .ne 2
248 .na
249 \fB\fBRTLD_DI_MMAPS\fR\fR
250 .ad
251 .sp .6
252 .RS 4n
253 Obtain segment mapping information for the \fIhandle\fR that is specified. The
254 \fIp\fR argument is a \fBDl_mapinfo_t\fR pointer (\fBDl_mapinfo_t *\fR\fIp\fR).
255 This structure can be initialized from the mapping count obtained from a
256 previous \fBRTLD_DI_MMAPCNT\fR request.
257 .sp
258 Segment mapping information is provided in an array of \fBmmapobj_result_t\fR
259 structures that originate from the \fBmmapobj\fR(2) of the associated object.
260 The \fBdlm_acnt\fR member, typically initialized from a previous
261 \fBRTLD_DI_MMAPCNT\fR request, indicates the number of enteries in a
262 \fBmmapobj_result_t\fR array. This array is assigned to the \fBdlm_maps\fR
263 member. This initialized structure is then passed to a \fBRTLD_DI_MMAPS\fR
264 request, where the segment mapping information is copied to the
265 \fBmmapobj_result_t\fR array. The \fBdlm_rcnt\fR member indicates the number of
266 \fBmmapobj_result_t\fR element entries that are returned. See \fBEXAMPLES\fR.
267 .RE
269 .sp
270 .ne 2
271 .na
272 \fB\fBRTLD_DI_SERINFO\fR\fR
273 .ad
274 .sp .6
275 .RS 4n
276 Obtain the library search paths for the \fIhandle\fR that is specified. The
277 \fIp\fR argument is a \fBDl_serinfo_t\fR pointer (\fBDl_serinfo_t *\fR\fIp\fR).
278 A user must first initialize the \fBDl_serinfo_t\fR structure with a
279 \fBRTLD_DI_SERINFOSIZE\fR request. See \fBEXAMPLES\fR.
280 .sp
281 The returned \fBDl_serinfo_t\fR structure contains \fBdls_cnt\fR
282 \fBDl_serpath_t\fR entries. Each entry's \fBdlp_name\fR member points to the
283 search path. The corresponding \fBdlp_info\fR member contains one of more flags
284 indicating the origin of the path. See the \fBLA_SER_*\fR flags that are
285 defined in <\fBlink.h\fR>.
286 .RE
288 .sp
289 .ne 2
290 .na
291 \fB\fBRTLD_DI_SERINFOSIZE\fR\fR
292 .ad
293 .sp .6
294 .RS 4n
295 Initialize a \fBDl_serinfo_t\fR structure for the \fIhandle\fR that is
296 specified, for use in a \fBRTLD_DI_SERINFO\fR request. Both the \fBdls_cnt\fR
297 and \fBdls_size\fR members are returned. The \fBdls_cnt\fR member indicates the
298 number of search paths that are applicable to the \fIhandle\fR. The
299 \fBdls_size\fR member indicates the total size of a \fBDl_serinfo_t\fR buffer
300 required to hold \fBdls_cnt\fR \fBDl_serpath_t\fR entries and the associated
301 search path strings. The \fIp\fR argument is a \fBDl_serinfo_t\fR pointer
302 (\fBDl_serinfo_t *\fR\fIp\fR).
303 .sp
304 To obtain the complete path information, a new \fBDl_serinfo_t\fR buffer of
305 size \fBdls_size\fR should be allocated. This new buffer should be initialized
306 with the \fBdls_cnt\fR and \fBdls_size\fR entries. The initialized buffer is
307 then passed to a \fBRTLD_DI_SERINFO\fR request. See \fBEXAMPLES\fR.
308 .RE
310 .sp
311 .ne 2
312 .na
313 \fB\fBRTLD_DI_ORIGIN\fR\fR
314 .ad
315 .sp .6
316 .RS 4n
317 Obtain the origin of the dynamic object that is associated with the
318 \fIhandle\fR. The \fIp\fR argument is a \fBchar\fR pointer (\fBchar
319 *\fR\fIp\fR). The \fBdirname\fR(3C) of the associated object's
320 \fBrealpath\fR(3C), which can be no larger than {\fBPATH_MAX\fR}, is copied to
321 the pointer \fIp\fR.
322 .RE
324 .sp
325 .ne 2
326 .na
327 \fB\fBRTLD_DI_GETSIGNAL\fR\fR
328 .ad
329 .sp .6
330 .RS 4n
331 Obtain the numeric signal number used by the runtime linker to kill the process
332 in the event of a fatal runtime error. The \fIp\fR argument is an \fBint\fR
333 pointer (\fBint *\fR\fIp\fR). The signal number is copied to the pointer
334 \fIp\fR.
335 .sp
336 By default, the signal used by the runtime linker to terminate a process is
337 \fBSIGKILL\fR. See \fBthr_kill\fR(3C). This default can be changed by calling
338 \fBdlinfo()\fR with \fBRTLD_DI_SETSIGNAL\fR or by setting the environment
339 variable \fBLD_SIGNAL\fR. See \fBld.so.1\fR(1).
340 .RE
342 .sp
343 .ne 2
344 .na
345 \fB\fBRTLD_DI_SETSIGNAL\fR\fR
346 .ad
347 .sp .6
348 .RS 4n
349 Provide a numeric signal number used by the runtime linker to kill the process
350 in the event of a fatal runtime error. The \fIp\fR argument is an \fBint\fR
351 pointer (\fBint *\fR\fIp\fR). The value pointed to by \fIp\fR is established as
352 the terminating signal value.
353 .sp
354 The current signal number used by the runtime linker to terminate a process can
355 be obtained from \fBdlinfo()\fR using \fBRTLD_DI_GETSIGNAL\fR. Use of the
356 \fBRTLD_DI_SETSIGNAL\fR option is equivalent to setting the environment
357 variable \fBLD_SIGNAL\fR. See \fBld.so.1\fR(1).
358 .RE
360 .SH RETURN VALUES
361 .sp
362 .LP
363 The \fBdlinfo()\fR function returns \(mi1 if the \fIrequest\fR is invalid, the
364 parameter \fIp\fR is \fINULL\fR, or the \fBDl_serinfo_t\fR structure is
365 uninitialized for a \fBRTLD_DI_SERINFO\fR request. \fBdlinfo()\fR also returns
366 \(mi1 if the \fIhandle\fR argument does not refer to a valid object opened by
367 \fBdlopen()\fR, or is not the special handle \fBRTLD_SELF\fR. Detailed
368 diagnostic information is available with \fBdlerror\fR(3C).
369 .SH EXAMPLES
370 .LP
371 \fBExample 1 \fRUse \fBdlinfo()\fR to obtain library search paths.
372 .sp
373 .LP
374 The following example demonstrates how a dynamic object can inspect the library
375 search paths that would be used to locate a simple filename with
376 \fBdlopen()\fR. For simplicity, error checking has been omitted.
378 .sp
379 .in +2
380 .nf
381 Dl_serinfo_t _info, *info = &_info;
382 Dl_serpath_t *path;
383 uint_t cnt;
385 /* determine search path count and required buffer size */
386 dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, info);
388 /* allocate new buffer and initialize */
389 info = malloc(_info.dls_size);
390 info->dls_size = _info.dls_size;
391 info->dls_cnt = _info.dls_cnt;
393 /* obtain sarch path information */
394 dlinfo(RTLD_SELF, RTLD_DI_SERINFO, info);
396 path = &info->dls_serpath[0];
398 for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) {
399 (void) printf("%2d: %s\en", cnt, path->dls_name);
400 }
401 .fi
402 .in -2
404 .LP
405 \fBExample 2 \fRUse \fBdlinfo()\fR to obtain segment information.
406 .sp
407 .LP
408 The following example demonstrates how a dynamic object can inspect its segment
409 mapping information. For simplicity, error checking has been omitted
411 .sp
412 .in +2
413 .nf
414 Dl_mapinfo_t mi;
415 uint_t cnt;
417 /* determine the number of segment mappings */
418 dlinfo(RTLD_SELF, RTLD_DI_MMAPCNT, &mi.dlm_acnt);
420 /* allocate the appropriate mapping array */
421 mi.dlm_maps = malloc(mi.dlm_acnt * sizeof (mmapobj_result_t));
423 /* obtain the mapping information */
424 dlinfo(RTLD_SELF, RTLD_DI_MMAPS, &mi);
426 for (cnt = 0; cnt < mi.dlm_rcnt; cnt++) {
427 (void) printf("addr=%x - memory size=%x\en",
428 mi.dlm_maps[cnt].mr_addr, mi.dlm_maps[cnt].mr_msize);
429 }
430 .fi
431 .in -2
433 .SH USAGE
434 .sp
435 .LP
436 The \fBdlinfo()\fR function is one of a family of functions that give the user
437 direct access to the dynamic linking facilities. These facilities are available
438 to dynamically-linked processes only. See the \fILinker and Libraries Guide\fR.
439 .SH ATTRIBUTES
440 .sp
441 .LP
442 See \fBattributes\fR(5) for descriptions of the following attributes:
443 .sp
445 .sp
446 .TS
447 box;
448 c | c
449 l | l .
450 ATTRIBUTE TYPE ATTRIBUTE VALUE
451 _
452 Interface Stability Stable
453 _
454 MT-Level MT-Safe
455 .TE
457 .SH SEE ALSO
458 .sp
459 .LP
460 \fBld\fR(1), \fBld.so.1\fR(1), \fBexec\fR(2), \fBioctl\fR(2), \fBmmapobj\fR(2),
461 \fBdirname\fR(3C), \fBdlclose\fR(3C), \fBdldump\fR(3C), \fBdlerror\fR(3C),
462 \fBdlopen\fR(3C), \fBdlsym\fR(3C), \fBputenv\fR(3C), \fBrealpath\fR(3C),
463 \fBthr_kill\fR(3C), \fBattributes\fR(5).
464 .sp
465 .LP
466 \fILinker and Libraries Guide\fR