usr/src/man/man3c/dlinfo.3c

   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>
  17
  18 \fBint\fR \fBdlinfo\fR(\fBvoid *\fR\fIhandle\fR, \fBint\fR \fIrequest\fR, \fBvoid *\fR\fIp\fR);
  19 .fi
  20
  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
  61
  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
  70
  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
  82
  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
  91
  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
  97
  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
 116
 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
 125
 126 .RE
 127
 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
 151
 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
 160
 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
 170
 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
 179
 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
 190
 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
 199
 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
 210
 211 .RE
 212
 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
 223
 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
 245
 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
 268
 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
 287
 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
 309
 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
 323
 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
 341
 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
 359
 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.
 377
 378 .sp
 379 .in +2
 380 .nf
 381     Dl_serinfo_t   _info, *info = &_info;
 382     Dl_serpath_t   *path;
 383     uint_t         cnt;
 384
 385     /* determine search path count and required buffer size */
 386     dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, info);
 387
 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;
 392
 393     /* obtain sarch path information */
 394     dlinfo(RTLD_SELF, RTLD_DI_SERINFO, info);
 395
 396     path = &info->dls_serpath[0];
 397
 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
 403
 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
 410
 411 .sp
 412 .in +2
 413 .nf
 414     Dl_mapinfo_t   mi;
 415     uint_t         cnt;
 416
 417     /* determine the number of segment mappings */
 418     dlinfo(RTLD_SELF, RTLD_DI_MMAPCNT, &mi.dlm_acnt);
 419
 420     /* allocate the appropriate mapping array */
 421     mi.dlm_maps = malloc(mi.dlm_acnt * sizeof (mmapobj_result_t));
 422
 423     /* obtain the mapping information */
 424     dlinfo(RTLD_SELF, RTLD_DI_MMAPS, &mi);
 425
 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
 432
 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
 444
 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
 456
 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