path: root/usr/src/man/man3c/dlinfo.3c

'\" te
.\" Copyright (c) 2009, Sun Microsystems,
.\" Inc.  All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH DLINFO 3C "Feb 4, 2009"
.SH NAME
dlinfo \- dynamic load information
.SH SYNOPSIS
.LP
.nf
#include <dlfcn.h>
#include <link.h>
#include <limits.h>
#include <sys/mman.h>

\fBint\fR \fBdlinfo\fR(\fBvoid *\fR\fIhandle\fR, \fBint\fR \fIrequest\fR, \fBvoid *\fR\fIp\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBdlinfo()\fR function sets or extracts information from the runtime
linker \fBld.so.1\fR(1). This function is loosely modeled after the
\fBioctl\fR(2) function. The \fIrequest\fR argument and a third argument of
varying type are passed to \fBdlinfo()\fR. The action taken by \fBdlinfo()\fR
depends on the value of the \fIrequest\fR that is provided.
.sp
.LP
The \fIhandle\fR argument is either the value that is returned from a
\fBdlopen\fR(3C) or \fBdlmopen()\fR call, or the special handle
\fBRTLD_SELF\fR. A \fIhandle\fR argument is required for all requests except
\fBRTLD_DI_CONFIGADDR\fR, \fBRTLD_DI_GETSIGNAL\fR, and \fBRTLD_DI_SETSIGNAL\fR.
If \fIhandle\fR is the value that is returned from a \fBdlopen()\fR or
\fBdlmopen()\fR call, the information returned by the \fBdlinfo()\fR call
pertains to the specified object. If \fIhandle\fR is the special handle
\fBRTLD_SELF\fR, the information returned by the \fBdlinfo()\fR call pertains
to the caller.
.sp
.LP
The \fIrequest\fR argument can take the following values:
.sp
.ne 2
.na
\fB\fBRTLD_DI_ARGSINFO\fR\fR
.ad
.sp .6
.RS 4n
Obtain process argument information. The \fIp\fR argument is a pointer
(\fBDl_argsinfo_t *\fR\fIp\fR). The following elements from this structure are
initialized:
.sp
.ne 2
.na
\fB\fBdla_argc\fR\fR
.ad
.RS 12n
The number of arguments passed to the process.
.RE

.sp
.ne 2
.na
\fB\fBdla_argv\fR\fR
.ad
.RS 12n
The argument array passed to the process.
.RE

.sp
.ne 2
.na
\fB\fBdla_envp\fR\fR
.ad
.RS 12n
The active environment variable array that is available to the process. This
element initially points to the environment variable array that is made
available to \fBexec\fR(2). This element can be updated should an alternative
environment be established by the process. See \fBputenv\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBdla_auxv\fR\fR
.ad
.RS 12n
The auxiliary vector array passed to the process.
.RE

A process can be established from executing the runtime linker directly from
the command line. See \fBld.so.1\fR(1). The \fBDl_argsinfo_t\fR information
reflects the information that is made available to the application regardless
of how the runtime linker has been invoked.
.RE

.sp
.ne 2
.na
\fB\fBRTLD_DI_CONFIGADDR\fR\fR
.ad
.sp .6
.RS 4n
Obtain the configuration file information. The \fIp\fR argument is a
\fBDl_info_t\fR pointer (\fBDl_info_t *\fR\fIp\fR). The following elements from
this structure are initialized:
.sp
.ne 2
.na
\fB\fBdli_fname\fR\fR
.ad
.RS 13n
The full name of the configuration file.
.RE

.sp
.ne 2
.na
\fB\fBdli_fbase\fR\fR
.ad
.RS 13n
The base address of the configuration file loaded into memory.
.RE

.RE

.sp
.ne 2
.na
\fB\fBRTLD_DI_LINKMAP\fR\fR
.ad
.sp .6
.RS 4n
Obtain the \fBLink_map\fR for the \fIhandle\fR that is specified. The \fIp\fR
argument points to a \fBLink_map\fR pointer (\fBLink_map **\fR\fIp\fR). The
actual storage for the \fBLink_map\fR structure is maintained by \fBld.so.1\fR.
.sp
The \fBLink_map\fR structure includes the following members:
.sp
.in +2
.nf
    unsigned long l_addr;      /* base address */
    char          *l_name;     /* object name */
    Elf32_Dyn     *l_ld;       /* .dynamic section */
    Link_map      *l_next;     /* next link object */
    Link_map      *l_prev;     /* previous link object */
    char          *l_refname;  /* filter reference name */
.fi
.in -2

.sp
.ne 2
.na
\fB\fBl_addr\fR\fR
.ad
.RS 13n
The base address of the object loaded into memory.
.RE

.sp
.ne 2
.na
\fB\fBl_name\fR\fR
.ad
.RS 13n
The full name of the loaded object. This full name is the filename of the
object as referenced by \fBld.so.1\fR.
.RE

.sp
.ne 2
.na
\fB\fBl_ld\fR\fR
.ad
.RS 13n
Points to the \fBSHT_DYNAMIC\fR structure.
.RE

.sp
.ne 2
.na
\fB\fBl_next\fR\fR
.ad
.RS 13n
The next \fBLink_map\fR on the link-map list. Other objects on the same
link-map list as the current object can be examined by following the
\fBl_next\fR and \fBl_prev\fR members.
.RE

.sp
.ne 2
.na
\fB\fBl_prev\fR\fR
.ad
.RS 13n
The previous \fBLink_map\fR on the link-map list.
.RE

.sp
.ne 2
.na
\fB\fBl_refname\fR\fR
.ad
.RS 13n
If the object that is referenced is a \fIfilter\fR, this member points to the
name of the object being filtered. If the object is not a \fIfilter\fR, this
member is \fB0\fR. See the \fILinker and Libraries Guide\fR.
.RE

.RE

.sp
.ne 2
.na
\fB\fBRTLD_DI_LMID\fR\fR
.ad
.sp .6
.RS 4n
Obtain the \fBID\fR for the link-map list upon which the \fIhandle\fR is
loaded. The \fIp\fR argument is a \fBLmid_t\fR pointer (\fBLmid_t *\fR\fIp\fR).
.RE

.sp
.ne 2
.na
\fB\fBRTLD_DI_MMAPCNT\fR\fR
.ad
.sp .6
.RS 4n
Determine the number of segment mappings for the \fIhandle\fR that is
specified, for use in a \fBRTLD_DI_MMAPS\fR request. The \fIp\fR argument is a
\fBuint_t\fR pointer (\fBuint_t *\fR\fIp\fR). On return from a
\fBRTLD_DI_MMAPCNT\fR request, the \fBuint_t\fR value that is pointed to by
\fIp\fR contains the number of segment mappings that the associated object
uses.
.sp
To obtain the complete mapping information for an object, a
\fBmmapobj_result_t\fR array for \fBRTLD_DI_MMAPCNT\fR entries must be
provided. This array is assigned to the \fBdlm_maps\fR member, and the number
of entries available in the arry are assigned to the \fBdlm_acnt\fR member.
This initialized structure is then passed to a \fBRTLD_DI_MMAPS\fR request. See
\fBEXAMPLES\fR.
.RE

.sp
.ne 2
.na
\fB\fBRTLD_DI_MMAPS\fR\fR
.ad
.sp .6
.RS 4n
Obtain segment mapping information for the \fIhandle\fR that is specified. The
\fIp\fR argument is a \fBDl_mapinfo_t\fR pointer (\fBDl_mapinfo_t *\fR\fIp\fR).
This structure can be initialized from the mapping count obtained from a
previous \fBRTLD_DI_MMAPCNT\fR request.
.sp
Segment mapping information is provided in an array of \fBmmapobj_result_t\fR
structures that originate from the \fBmmapobj\fR(2) of the associated object.
The \fBdlm_acnt\fR member, typically initialized from a previous
\fBRTLD_DI_MMAPCNT\fR request, indicates the number of enteries in a
\fBmmapobj_result_t\fR array. This array is assigned to the \fBdlm_maps\fR
member. This initialized structure is then passed to a \fBRTLD_DI_MMAPS\fR
request, where the segment mapping information is copied to the
\fBmmapobj_result_t\fR array. The \fBdlm_rcnt\fR member indicates the number of
\fBmmapobj_result_t\fR element entries that are returned. See \fBEXAMPLES\fR.
.RE

.sp
.ne 2
.na
\fB\fBRTLD_DI_SERINFO\fR\fR
.ad
.sp .6
.RS 4n
Obtain the library search paths for the \fIhandle\fR that is specified. The
\fIp\fR argument is a \fBDl_serinfo_t\fR pointer (\fBDl_serinfo_t *\fR\fIp\fR).
A user must first initialize the \fBDl_serinfo_t\fR structure with a
\fBRTLD_DI_SERINFOSIZE\fR request. See \fBEXAMPLES\fR.
.sp
The returned \fBDl_serinfo_t\fR structure contains \fBdls_cnt\fR
\fBDl_serpath_t\fR entries. Each entry's \fBdlp_name\fR member points to the
search path. The corresponding \fBdlp_info\fR member contains one of more flags
indicating the origin of the path. See the \fBLA_SER_*\fR flags that are
defined in <\fBlink.h\fR>.
.RE

.sp
.ne 2
.na
\fB\fBRTLD_DI_SERINFOSIZE\fR\fR
.ad
.sp .6
.RS 4n
Initialize a \fBDl_serinfo_t\fR structure for the \fIhandle\fR that is
specified, for use in a \fBRTLD_DI_SERINFO\fR request. Both the \fBdls_cnt\fR
and \fBdls_size\fR members are returned. The \fBdls_cnt\fR member indicates the
number of search paths that are applicable to the \fIhandle\fR. The
\fBdls_size\fR member indicates the total size of a \fBDl_serinfo_t\fR buffer
required to hold \fBdls_cnt\fR \fBDl_serpath_t\fR entries and the associated
search path strings. The \fIp\fR argument is a \fBDl_serinfo_t\fR pointer
(\fBDl_serinfo_t *\fR\fIp\fR).
.sp
To obtain the complete path information, a new \fBDl_serinfo_t\fR buffer of
size \fBdls_size\fR should be allocated. This new buffer should be initialized
with the \fBdls_cnt\fR and \fBdls_size\fR entries. The initialized buffer is
then passed to a \fBRTLD_DI_SERINFO\fR request. See \fBEXAMPLES\fR.
.RE

.sp
.ne 2
.na
\fB\fBRTLD_DI_ORIGIN\fR\fR
.ad
.sp .6
.RS 4n
Obtain the origin of the dynamic object that is associated with the
\fIhandle\fR. The \fIp\fR argument is a \fBchar\fR pointer (\fBchar
*\fR\fIp\fR). The \fBdirname\fR(3C) of the associated object's
\fBrealpath\fR(3C), which can be no larger than {\fBPATH_MAX\fR}, is copied to
the pointer \fIp\fR.
.RE

.sp
.ne 2
.na
\fB\fBRTLD_DI_GETSIGNAL\fR\fR
.ad
.sp .6
.RS 4n
Obtain the numeric signal number used by the runtime linker to kill the process
in the event of a fatal runtime error. The \fIp\fR argument is an \fBint\fR
pointer (\fBint *\fR\fIp\fR). The signal number is copied to the pointer
\fIp\fR.
.sp
By default, the signal used by the runtime linker to terminate a process is
\fBSIGKILL\fR. See \fBthr_kill\fR(3C). This default can be changed by calling
\fBdlinfo()\fR with \fBRTLD_DI_SETSIGNAL\fR or by setting the environment
variable \fBLD_SIGNAL\fR. See \fBld.so.1\fR(1).
.RE

.sp
.ne 2
.na
\fB\fBRTLD_DI_SETSIGNAL\fR\fR
.ad
.sp .6
.RS 4n
Provide a numeric signal number used by the runtime linker to kill the process
in the event of a fatal runtime error. The \fIp\fR argument is an \fBint\fR
pointer (\fBint *\fR\fIp\fR). The value pointed to by \fIp\fR is established as
the terminating signal value.
.sp
The current signal number used by the runtime linker to terminate a process can
be obtained from \fBdlinfo()\fR using \fBRTLD_DI_GETSIGNAL\fR. Use of the
\fBRTLD_DI_SETSIGNAL\fR option is equivalent to setting the environment
variable \fBLD_SIGNAL\fR. See \fBld.so.1\fR(1).
.RE

.SH RETURN VALUES
.sp
.LP
The \fBdlinfo()\fR function returns \(mi1 if the \fIrequest\fR is invalid, the
parameter \fIp\fR is \fINULL\fR, or the \fBDl_serinfo_t\fR structure is
uninitialized for a \fBRTLD_DI_SERINFO\fR request. \fBdlinfo()\fR also returns
\(mi1 if the \fIhandle\fR argument does not refer to a valid object opened by
\fBdlopen()\fR, or is not the special handle \fBRTLD_SELF\fR. Detailed
diagnostic information is available with \fBdlerror\fR(3C).
.SH EXAMPLES
.LP
\fBExample 1 \fRUse \fBdlinfo()\fR to obtain library search paths.
.sp
.LP
The following example demonstrates how a dynamic object can inspect the library
search paths that would be used to locate a simple filename with
\fBdlopen()\fR. For simplicity, error checking has been omitted.

.sp
.in +2
.nf
    Dl_serinfo_t   _info, *info = &_info;
    Dl_serpath_t   *path;
    uint_t         cnt;

    /* determine search path count and required buffer size */
    dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, info);

    /* allocate new buffer and initialize */
    info = malloc(_info.dls_size);
    info->dls_size = _info.dls_size;
    info->dls_cnt = _info.dls_cnt;

    /* obtain sarch path information */
    dlinfo(RTLD_SELF, RTLD_DI_SERINFO, info);

    path = &info->dls_serpath[0];

    for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) {
        (void) printf("%2d: %s\en", cnt, path->dls_name);
    }
.fi
.in -2

.LP
\fBExample 2 \fRUse \fBdlinfo()\fR to obtain segment information.
.sp
.LP
The following example demonstrates how a dynamic object can inspect its segment
mapping information. For simplicity, error checking has been omitted

.sp
.in +2
.nf
    Dl_mapinfo_t   mi;
    uint_t         cnt;

    /* determine the number of segment mappings */
    dlinfo(RTLD_SELF, RTLD_DI_MMAPCNT, &mi.dlm_acnt);

    /* allocate the appropriate mapping array */
    mi.dlm_maps = malloc(mi.dlm_acnt * sizeof (mmapobj_result_t));

    /* obtain the mapping information */
    dlinfo(RTLD_SELF, RTLD_DI_MMAPS, &mi);

    for (cnt = 0; cnt < mi.dlm_rcnt; cnt++) {
        (void) printf("addr=%x - memory size=%x\en",
            mi.dlm_maps[cnt].mr_addr, mi.dlm_maps[cnt].mr_msize);
    }
.fi
.in -2

.SH USAGE
.sp
.LP
The \fBdlinfo()\fR function is one of a family of functions that give the user
direct access to the dynamic linking facilities. These facilities are available
to dynamically-linked processes only. See the \fILinker and Libraries Guide\fR.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Stable
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBld\fR(1), \fBld.so.1\fR(1), \fBexec\fR(2), \fBioctl\fR(2), \fBmmapobj\fR(2),
\fBdirname\fR(3C), \fBdlclose\fR(3C), \fBdldump\fR(3C), \fBdlerror\fR(3C),
\fBdlopen\fR(3C), \fBdlsym\fR(3C), \fBputenv\fR(3C), \fBrealpath\fR(3C),
\fBthr_kill\fR(3C), \fBattributes\fR(5)
.sp
.LP
\fILinker and Libraries Guide\fR