Standard C Library Functions dlinfo(3C)
NAME
dlinfo - dynamic load information
SYNOPSIS
#include
#include
#include
#include
int dlinfo(void *handle, int request, void *p);
DESCRIPTION
The dlinfo() function sets or extracts information from the
runtime linker ld.so.1(1). This function is loosely modeled
after the ioctl(2) function. The request argument and a
third argument of varying type are passed to dlinfo(). The
action taken by dlinfo() depends on the value of the request
that is provided.
The handle argument is either the value that is returned
from a dlopen(3C) or dlmopen() call, or the special handle
RTLDSELF. A handle argument is required for all requests
except RTLDICONFIGADR, RTLDIGETSIGNAL, and
RTLDISETSIGNAL. If handle is the value that is returned
from a dlopen() or dlmopen() call, the information returned
by the dlinfo() call pertains to the specified object. If
handle is the special handle RTLDSELF, the information
returned by the dlinfo() call pertains to the caller.
The request argument can take the following values:
RTLDIARGSINFO
Obtain process argument information. The p argument is a
pointer (Dlargsinfot *p). The following elements from
this structure are initialized:
dlaargc The number of arguments passed to the pro-
cess.
dlaargv The argument array passed to the process.
dlaenvp 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 exec(2).
This element can be updated should an
SunOS 5.11 Last change: 4 Feb 2009 1
Standard C Library Functions dlinfo(3C)
alternative environment be established by
the process. See putenv(3C).
dlaauxv The auxiliary vector array passed to the
process.
A process can be established from executing the runtime
linker directly from the command line. See ld.so.1(1).
The Dlargsinfot information reflects the information
that is made available to the application regardless of
how the runtime linker has been invoked.
RTLDICONFIGADR
Obtain the configuration file information. The p argu-
ment is a Dlinfot pointer (Dlinfot *p). The follow-
ing elements from this structure are initialized:
dlifname The full name of the configuration file.
dlifbase The base address of the configuration file
loaded into memory.
RTLDILINKMAP
Obtain the Linkmap for the handle that is specified.
The p argument points to a Linkmap pointer (Linkmap
**p). The actual storage for the Linkmap structure is
maintained by ld.so.1.
The Linkmap structure includes the following members:
unsigned long laddr; /* base address */
char *lname; /* object name */
Elf32Dyn *lld; /* .dynamic section */
Linkmap *lnext; /* next link object */
Linkmap *lprev; /* previous link object */
char *lrefname; /* filter reference name */
laddr The base address of the object loaded into
memory.
lname The full name of the loaded object. This
full name is the filename of the object as
referenced by ld.so.1.
SunOS 5.11 Last change: 4 Feb 2009 2
Standard C Library Functions dlinfo(3C)
lld Points to the SHTDYNAMIC structure.
lnext The next Linkmap on the link-map list.
Other objects on the same link-map list as
the current object can be examined by fol-
lowing the lnext and lprev members.
lprev The previous Linkmap on the link-map list.
lrefname If the object that is referenced is a
filter, this member points to the name of
the object being filtered. If the object is
not a filter, this member is 0. See the
Linker and Libraries Guide.
RTLDILMID
Obtain the ID for the link-map list upon which the han-
dle is loaded. The p argument is a Lmidt pointer
(Lmidt *p).
RTLDIMAPCNT
Determine the number of segment mappings for the handle
that is specified, for use in a RTLDIMAPS request.
The p argument is a uintt pointer (uintt *p). On
return from a RTLDIMAPCNT request, the uintt value
that is pointed to by p contains the number of segment
mappings that the associated object uses.
To obtain the complete mapping information for an
object, a mmapobjresultt array for RTLDIMAPCNT
entries must be provided. This array is assigned to the
dlmmaps member, and the number of entries available in
the arry are assigned to the dlmacnt member. This ini-
tialized structure is then passed to a RTLDIMAPS
request. See EXAMPLES.
RTLDIMAPS
Obtain segment mapping information for the handle that
is specified. The p argument is a Dlmapinfot pointer
(Dlmapinfot *p). This structure can be initialized
from the mapping count obtained from a previous
RTLDIMAPCNT request.
SunOS 5.11 Last change: 4 Feb 2009 3
Standard C Library Functions dlinfo(3C)
Segment mapping information is provided in an array of
mmapobjresultt structures that originate from the mma-
pobj(2) of the associated object. The dlmacnt member,
typically initialized from a previous RTLDIMAPCNT
request, indicates the number of enteries in a
mmapobjresultt array. This array is assigned to the
dlmmaps member. This initialized structure is then
passed to a RTLDIMAPS request, where the segment
mapping information is copied to the mmapobjresultt
array. The dlmrcnt member indicates the number of
mmapobjresultt element entries that are returned. See
EXAMPLES.
RTLDISERINFO
Obtain the library search paths for the handle that is
specified. The p argument is a Dlserinfot pointer
(Dlserinfot *p). A user must first initialize the
Dlserinfot structure with a RTLDISERINFOSIZE
request. See EXAMPLES.
The returned Dlserinfot structure contains dlscnt
Dlserpatht entries. Each entry's dlpname member
points to the search path. The corresponding dlpinfo
member contains one of more flags indicating the origin
of the path. See the LASER* flags that are defined in
.
RTLDISERINFOSIZE
Initialize a Dlserinfot structure for the handle that
is specified, for use in a RTLDISERINFO request. Both
the dlscnt and dlssize members are returned. The
dlscnt member indicates the number of search paths that
are applicable to the handle. The dlssize member indi-
cates the total size of a Dlserinfot buffer required
to hold dlscnt Dlserpatht entries and the associated
search path strings. The p argument is a Dlserinfot
pointer (Dlserinfot *p).
To obtain the complete path information, a new
Dlserinfot buffer of size dlssize should be allo-
cated. This new buffer should be initialized with the
dlscnt and dlssize entries. The initialized buffer is
then passed to a RTLDISERINFO request. See EXAMPLES.
RTLDIORIGIN
Obtain the origin of the dynamic object that is
SunOS 5.11 Last change: 4 Feb 2009 4
Standard C Library Functions dlinfo(3C)
associated with the handle. The p argument is a char
pointer (char *p). The dirname(3C) of the associated
object's realpath(3C), which can be no larger than
{PATHMAX}, is copied to the pointer p.
RTLDIGETSIGNAL
Obtain the numeric signal number used by the runtime
linker to kill the process in the event of a fatal run-
time error. The p argument is an int pointer (int *p).
The signal number is copied to the pointer p.
By default, the signal used by the runtime linker to
terminate a process is SIGKIL. See thrkill(3C). This
default can be changed by calling dlinfo() with
RTLDISETSIGNAL or by setting the environment variable
LDSIGNAL. See ld.so.1(1).
RTLDISETSIGNAL
Provide a numeric signal number used by the runtime
linker to kill the process in the event of a fatal run-
time error. The p argument is an int pointer (int *p).
The value pointed to by p is established as the ter-
minating signal value.
The current signal number used by the runtime linker to
terminate a process can be obtained from dlinfo() using
RTLDIGETSIGNAL. Use of the RTLDISETSIGNAL option
is equivalent to setting the environment variable
LDSIGNAL. See ld.so.1(1).
RETURN VALUES
The dlinfo() function returns -1 if the request is invalid,
the parameter p is NUL, or the Dlserinfot structure is
uninitialized for a RTLDISERINFO request. dlinfo() also
returns -1 if the handle argument does not refer to a valid
object opened by dlopen(), or is not the special handle
RTLDSELF. Detailed diagnostic information is available with
dlerror(3C).
EXAMPLES
Example 1 Use dlinfo() to obtain library search paths.
The following example demonstrates how a dynamic object can
inspect the library search paths that would be used to
locate a simple filename with dlopen(). For simplicity,
error checking has been omitted.
SunOS 5.11 Last change: 4 Feb 2009 5
Standard C Library Functions dlinfo(3C)
Dlserinfot info, *info = &info;
Dlserpatht *path;
uintt cnt;
/* determine search path count and required buffer size */
dlinfo(RTLDSELF, RTLDISERINFOSIZE, info);
/* allocate new buffer and initialize */
info = malloc(info.dlssize);
info->dlssize = info.dlssize;
info->dlscnt = info.dlscnt;
/* obtain sarch path information */
dlinfo(RTLDSELF, RTLDISERINFO, info);
path = &info->dlsserpath[0];
for (cnt = 1; cnt <= info->dlscnt; cnt], path]) {
(void) printf("%2d: %s\n", cnt, path->dlsname);
}
Example 2 Use dlinfo() to obtain segment information.
The following example demonstrates how a dynamic object can
inspect its segment mapping information. For simplicity,
error checking has been omitted
Dlmapinfot mi;
uintt cnt;
/* determine the number of segment mappings */
dlinfo(RTLDSELF, RTLDIMAPCNT, &mi.dlmacnt);
/* allocate the appropriate mapping array */
mi.dlmmaps = malloc(mi.dlmacnt * sizeof (mmapobjresultt));
/* obtain the mapping information */
dlinfo(RTLDSELF, RTLDIMAPS, &mi);
for (cnt = 0; cnt < mi.dlmrcnt; cnt]) {
(void) printf("addr=%x - memory size=%x\n",
mi.dlmmaps[cnt].mraddr, mi.dlmmaps[cnt].mrmsize);
}
USAGE
The dlinfo() function is one of a family of functions that
give the user direct access to the dynamic linking facili-
ties. These facilities are available to dynamically-linked
SunOS 5.11 Last change: 4 Feb 2009 6
Standard C Library Functions dlinfo(3C)
processes only. See the Linker and Libraries Guide.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Stable
MT-Level MT-Safe
SEE ALSO
ld(1), ld.so.1(1), exec(2), ioctl(2), mmapobj(2),
dirname(3C), dlclose(3C), dldump(3C), dlerror(3C),
dlopen(3C), dlsym(3C), putenv(3C), realpath(3C),
thrkill(3C), attributes(5).
Linker and Libraries Guide
SunOS 5.11 Last change: 4 Feb 2009 7
|
