1dlinfo(3C) Standard C Library Functions dlinfo(3C)
2
6 dlinfo - dynamic load information
7
9 #include <dlfcn.h>
10 #include <link.h>
11 #include <limits.h>
12 #include <sys/mman.h>
13 int dlinfo(void *handle, int request, void *p);
15
18 The dlinfo() function sets or extracts information from the runtime
19 linker ld.so.1(1). This function is loosely modeled after the ioctl(2)
20 function. The request argument and a third argument of varying type are
21 passed to dlinfo(). The action taken by dlinfo() depends on the value
22 of the request that is provided.
23 The handle argument is either the value that is returned from a
26 dlopen(3C) or dlmopen() call, or the special handle RTLD_SELF. A handle
27 argument is required for all requests except RTLD_DI_CONFIGADDR,
28 RTLD_DI_GETSIGNAL, and RTLD_DI_SETSIGNAL. If handle is the value that
29 is returned from a dlopen() or dlmopen() call, the information returned
30 by the dlinfo() call pertains to the specified object. If handle is the
31 special handle RTLD_SELF, the information returned by the dlinfo() call
32 pertains to the caller.
33 The request argument can take the following values:
36 RTLD_DI_ARGSINFO
38 Obtain process argument information. The p argument is a pointer
40 (Dl_argsinfo_t *p). The following elements from this structure are
41 initialized:
42 dla_argc The number of arguments passed to the process.
44 dla_argv The argument array passed to the process.
47 dla_envp The active environment variable array that is available
50 to the process. This element initially points to the
51 environment variable array that is made available to
52 exec(2). This element can be updated should an alterna‐
53 tive environment be established by the process. See
54 putenv(3C).
55 dla_auxv The auxiliary vector array passed to the process.
58 A process can be established from executing the runtime linker
60 directly from the command line. See ld.so.1(1). The Dl_argsinfo_t
61 information reflects the information that is made available to the
62 application regardless of how the runtime linker has been invoked.
63 RTLD_DI_CONFIGADDR
66 Obtain the configuration file information. The p argument is a
68 Dl_info_t pointer (Dl_info_t *p). The following elements from this
69 structure are initialized:
70 dli_fname The full name of the configuration file.
72 dli_fbase The base address of the configuration file loaded into
75 memory.
76 RTLD_DI_LINKMAP
80 Obtain the Link_map for the handle that is specified. The p argu‐
82 ment points to a Link_map pointer (Link_map **p). The actual stor‐
83 age for the Link_map structure is maintained by ld.so.1.
84 The Link_map structure includes the following members:
86 unsigned long l_addr; /* base address */
88 char *l_name; /* object name */
89 Elf32_Dyn *l_ld; /* .dynamic section */
90 Link_map *l_next; /* next link object */
91 Link_map *l_prev; /* previous link object */
92 char *l_refname; /* filter reference name */
93 l_addr The base address of the object loaded into memory.
96 l_name The full name of the loaded object. This full name is
99 the filename of the object as referenced by ld.so.1.
100 l_ld Points to the SHT_DYNAMIC structure.
103 l_next The next Link_map on the link-map list. Other objects
106 on the same link-map list as the current object can be
107 examined by following the l_next and l_prev members.
108 l_prev The previous Link_map on the link-map list.
111 l_refname If the object that is referenced is a filter, this
114 member points to the name of the object being fil‐
115 tered. If the object is not a filter, this member is
116 0. See the Linker and Libraries Guide.
117 RTLD_DI_LMID
121 Obtain the ID for the link-map list upon which the handle is
123 loaded. The p argument is a Lmid_t pointer (Lmid_t *p).
124 RTLD_DI_MMAPCNT
127 Determine the number of segment mappings for the handle that is
129 specified, for use in a RTLD_DI_MMAPS request. The p argument is a
130 uint_t pointer (uint_t *p). On return from a RTLD_DI_MMAPCNT
131 request, the uint_t value that is pointed to by p contains the num‐
132 ber of segment mappings that the associated object uses.
133 To obtain the complete mapping information for an object, a
135 mmapobj_result_t array for RTLD_DI_MMAPCNT entries must be pro‐
136 vided. This array is assigned to the dlm_maps member, and the num‐
137 ber of entries available in the arry are assigned to the dlm_acnt
138 member. This initialized structure is then passed to a
139 RTLD_DI_MMAPS request. See EXAMPLES.
140 RTLD_DI_MMAPS
143 Obtain segment mapping information for the handle that is speci‐
145 fied. The p argument is a Dl_mapinfo_t pointer (Dl_mapinfo_t *p).
146 This structure can be initialized from the mapping count obtained
147 from a previous RTLD_DI_MMAPCNT request.
148 Segment mapping information is provided in an array of
150 mmapobj_result_t structures that originate from the mmapobj(2) of
151 the associated object. The dlm_acnt member, typically initialized
152 from a previous RTLD_DI_MMAPCNT request, indicates the number of
153 enteries in a mmapobj_result_t array. This array is assigned to
154 the dlm_maps member. This initialized structure is then passed to a
155 RTLD_DI_MMAPS request, where the segment mapping information is
156 copied to the mmapobj_result_t array. The dlm_rcnt member indicates
157 the number of mmapobj_result_t element entries that are returned.
158 See EXAMPLES.
159 RTLD_DI_SERINFO
162 Obtain the library search paths for the handle that is specified.
164 The p argument is a Dl_serinfo_t pointer (Dl_serinfo_t *p). A user
165 must first initialize the Dl_serinfo_t structure with a
166 RTLD_DI_SERINFOSIZE request. See EXAMPLES.
167 The returned Dl_serinfo_t structure contains dls_cnt Dl_serpath_t
169 entries. Each entry's dlp_name member points to the search path.
170 The corresponding dlp_info member contains one of more flags indi‐
171 cating the origin of the path. See the LA_SER_* flags that are
172 defined in <link.h>.
173 RTLD_DI_SERINFOSIZE
176 Initialize a Dl_serinfo_t structure for the handle that is speci‐
178 fied, for use in a RTLD_DI_SERINFO request. Both the dls_cnt and
179 dls_size members are returned. The dls_cnt member indicates the
180 number of search paths that are applicable to the handle. The
181 dls_size member indicates the total size of a Dl_serinfo_t buffer
182 required to hold dls_cnt Dl_serpath_t entries and the associated
183 search path strings. The p argument is a Dl_serinfo_t pointer
184 (Dl_serinfo_t *p).
185 To obtain the complete path information, a new Dl_serinfo_t buffer
187 of size dls_size should be allocated. This new buffer should be
188 initialized with the dls_cnt and dls_size entries. The initialized
189 buffer is then passed to a RTLD_DI_SERINFO request. See EXAMPLES.
190 RTLD_DI_ORIGIN
193 Obtain the origin of the dynamic object that is associated with the
195 handle. The p argument is a char pointer (char *p). The dirname(3C)
196 of the associated object's realpath(3C), which can be no larger
197 than {PATH_MAX}, is copied to the pointer p.
198 RTLD_DI_GETSIGNAL
201 Obtain the numeric signal number used by the runtime linker to kill
203 the process in the event of a fatal runtime error. The p argument
204 is an int pointer (int *p). The signal number is copied to the
205 pointer p.
206 By default, the signal used by the runtime linker to terminate a
208 process is SIGKILL. See thr_kill(3C). This default can be changed
209 by calling dlinfo() with RTLD_DI_SETSIGNAL or by setting the envi‐
210 ronment variable LD_SIGNAL. See ld.so.1(1).
211 RTLD_DI_SETSIGNAL
214 Provide a numeric signal number used by the runtime linker to kill
216 the process in the event of a fatal runtime error. The p argument
217 is an int pointer (int *p). The value pointed to by p is estab‐
218 lished as the terminating signal value.
219 The current signal number used by the runtime linker to terminate a
221 process can be obtained from dlinfo() using RTLD_DI_GETSIGNAL. Use
222 of the RTLD_DI_SETSIGNAL option is equivalent to setting the envi‐
223 ronment variable LD_SIGNAL. See ld.so.1(1).
224
227 The dlinfo() function returns −1 if the request is invalid, the parame‐
228 ter p is NULL, or the Dl_serinfo_t structure is uninitialized for a
229 RTLD_DI_SERINFO request. dlinfo() also returns −1 if the handle argu‐
230 ment does not refer to a valid object opened by dlopen(), or is not the
231 special handle RTLD_SELF. Detailed diagnostic information is available
232 with dlerror(3C).
233
235 Example 1 Use dlinfo() to obtain library search paths.
236 The following example demonstrates how a dynamic object can inspect the
239 library search paths that would be used to locate a simple filename
240 with dlopen(). For simplicity, error checking has been omitted.
241 Dl_serinfo_t _info, *info = &_info;
244 Dl_serpath_t *path;
245 uint_t cnt;
246 /* determine search path count and required buffer size */
248 dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, info);
249 /* allocate new buffer and initialize */
251 info = malloc(_info.dls_size);
252 info->dls_size = _info.dls_size;
253 info->dls_cnt = _info.dls_cnt;
254 /* obtain sarch path information */
256 dlinfo(RTLD_SELF, RTLD_DI_SERINFO, info);
257 path = &info->dls_serpath[0];
259 for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) {
261 (void) printf("%2d: %s\n", cnt, path->dls_name);
262 }
263 Example 2 Use dlinfo() to obtain segment information.
266 The following example demonstrates how a dynamic object can inspect its
269 segment mapping information. For simplicity, error checking has been
270 omitted
271 Dl_mapinfo_t mi;
274 uint_t cnt;
275 /* determine the number of segment mappings */
277 dlinfo(RTLD_SELF, RTLD_DI_MMAPCNT, &mi.dlm_acnt);
278 /* allocate the appropriate mapping array */
280 mi.dlm_maps = malloc(mi.dlm_acnt * sizeof (mmapobj_result_t));
281 /* obtain the mapping information */
283 dlinfo(RTLD_SELF, RTLD_DI_MMAPS, &mi);
284 for (cnt = 0; cnt < mi.dlm_rcnt; cnt++) {
286 (void) printf("addr=%x - memory size=%x\n",
287 mi.dlm_maps[cnt].mr_addr, mi.dlm_maps[cnt].mr_msize);
288 }
289
292 The dlinfo() function is one of a family of functions that give the
293 user direct access to the dynamic linking facilities. These facilities
294 are available to dynamically-linked processes only. See the Linker and
295 Libraries Guide.
296
298 See attributes(5) for descriptions of the following attributes:
299 ┌─────────────────────────────┬─────────────────────────────┐
304 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
305 ├─────────────────────────────┼─────────────────────────────┤
306 │Interface Stability │Stable │
307 ├─────────────────────────────┼─────────────────────────────┤
308 │MT-Level │MT-Safe │
309 └─────────────────────────────┴─────────────────────────────┘
310
312 ld(1), ld.so.1(1), exec(2), ioctl(2), mmapobj(2), dirname(3C),
313 dlclose(3C), dldump(3C), dlerror(3C), dlopen(3C), dlsym(3C),
314 putenv(3C), realpath(3C), thr_kill(3C), attributes(5).
315 Linker and Libraries Guide
318SunOS 5.11 4 Feb 2009 dlinfo(3C)