268 lines
6.7 KiB
Groff
268 lines
6.7 KiB
Groff
.\"
|
|
.\" Copyright (c) 2003 Alexey Zelkin <phantom@FreeBSD.org>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd February 14, 2003
|
|
.Os
|
|
.Dt DLINFO 3
|
|
.Sh NAME
|
|
.Nm dlinfo
|
|
.Nd information about dynamically loaded object
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In link.h
|
|
.In dlfcn.h
|
|
.Ft int
|
|
.Fn dlinfo "void * __restrict handle" "int request" "void * __restrict p"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn dlinfo
|
|
function provides information about dynamically loaded object.
|
|
The action taken by
|
|
.Fn dlinfo
|
|
and exact meaning and type of
|
|
.Fa p
|
|
argument depend on value of the
|
|
.Fa request
|
|
argument provided by caller.
|
|
.Pp
|
|
A
|
|
.Fa handle
|
|
argument is either the value returned from a
|
|
.Fn dlopen
|
|
function call or special handle
|
|
.Dv RTLD_SELF .
|
|
If handle is the value returned from
|
|
.Fn dlopen
|
|
call, the information returned by the
|
|
.Fn dlinfo
|
|
function is pertains the specified object.
|
|
If handle is the special handle
|
|
.Dv RTLD_SELF ,
|
|
the information returned pertains to the caller itself.
|
|
.Pp
|
|
The following are possible values for
|
|
.Fa request
|
|
argument to be passed into
|
|
.Fn dlinfo :
|
|
.Bl -tag -width Ds
|
|
.It RTLD_DI_LINKMAP
|
|
Retrieve the Link_map (or
|
|
.Ft struct link_map )
|
|
structure pointer for
|
|
.Fa handle
|
|
specified.
|
|
On successful return the
|
|
.Fa p
|
|
argument is filled with pointer to Link_map structure
|
|
.Ft ( Link_map **p )
|
|
describing shared object specified by
|
|
.Fa handle
|
|
argument.
|
|
.Ft Link_map
|
|
stuctures are maintained as double-linked list by
|
|
.Xr ld.so 1
|
|
in same order as
|
|
.Fn dlopen
|
|
and
|
|
.Fn dlclose
|
|
are called.
|
|
See
|
|
.Sx EXAMPLES
|
|
(Example 1.)
|
|
.Pp
|
|
The
|
|
.Ft Link_map
|
|
structure is defined in <link.h> and have following members:
|
|
.Pp
|
|
.Bd -literal
|
|
caddr_t l_addr; /* Base Address of library */
|
|
const char *l_name; /* Absolute Path to Library */
|
|
const void *l_ld; /* Pointer to .dynamic in memory */
|
|
struct link_map *l_next, /* linked list of of mapped libs */
|
|
*l_prev;
|
|
.Ed
|
|
.Bl -tag -width Ds
|
|
.It l_addr
|
|
The base address of the object loaded into memory.
|
|
.It l_name
|
|
The full name of loaded shared object.
|
|
.It l_ld
|
|
The address of dynamic linking information segment
|
|
.Dv ( PT_DYNAMIC )
|
|
loaded into memory.
|
|
.It l_next
|
|
The next Link_map structure on the link-map list.
|
|
.It l_prev
|
|
The previous Link_map structure on the link-map list.
|
|
.El
|
|
.It RTLD_DI_SERINFO
|
|
Retrieve the library search paths associated with given
|
|
.Fa handle
|
|
argument.
|
|
The
|
|
.Fa p
|
|
argument should point to
|
|
.Ft Dl_serinfo
|
|
structure buffer
|
|
.Fa ( Dl_serinfo *p ) .
|
|
.Ft Dl_serinfo
|
|
structure must be initialized first with a
|
|
.Dv RTLD_DI_SERINFOSIZE
|
|
request.
|
|
.Pp
|
|
The returned
|
|
.Ft Dl_serinfo
|
|
structure contains
|
|
.Dv dls_cnt
|
|
.Ft Dl_serpath
|
|
entries.
|
|
Each entry's
|
|
.Dv dlp_name
|
|
field points to the search path.
|
|
The corresponding
|
|
.Dv dlp_info
|
|
field contains one of more flags indicating the origin of the path (see the
|
|
.Dv LA_SER_*
|
|
flags defined in <link.h> header file.)
|
|
See
|
|
.Sx EXAMPLES
|
|
(Example 2) for usage example.
|
|
.It RTLD_DI_SERINFOSIZE
|
|
Initialize a
|
|
.Ft Dl_serinfo
|
|
structure for use in a
|
|
.Dv RTLD_DI_SERINFO
|
|
request.
|
|
Both the
|
|
.Dv dls_cnt
|
|
and
|
|
.Dv dls_size
|
|
fields are returned to indicate the number of search paths applicable
|
|
to the handle, and the total size of a
|
|
.Ft Dl_serinfo
|
|
buffer required to hold
|
|
.Dv dls_cnt
|
|
.Ft Dl_serpath
|
|
entries and the associated search path strings.
|
|
See
|
|
.Sx EXAMPLES
|
|
(Example 2) for usage example.
|
|
.It RTLD_DI_ORIGIN
|
|
Retrieve the origin of the dynamic object associated with the handle.
|
|
On successful return
|
|
.Fa p
|
|
argument is filled with
|
|
.Ft char
|
|
pointer
|
|
.Ft ( char *p ) .
|
|
.El
|
|
.Sh EXAMPLES
|
|
Example 1: Using
|
|
.Fn dlinfo
|
|
to retrieve Link_map structure.
|
|
.Pp
|
|
The following example shows how dynamic library can detect the list
|
|
of shared libraries loaded after caller's one.
|
|
For simplicity, error checking has been omitted.
|
|
.Bd -literal
|
|
Link_map *map;
|
|
|
|
dlinfo(RTLD_SELF, RTLD_DI_LINKMAP, &map);
|
|
|
|
while (map != NULL) {
|
|
printf("%p: %s\n", map->l_addr, map->l_name);
|
|
map = map->l_next;
|
|
}
|
|
.Ed
|
|
.Pp
|
|
Example 2: Using
|
|
.Fn dlinfo
|
|
to retrieve the library search paths.
|
|
.Pp
|
|
The following example shows how a dynamic object can inspect the library
|
|
search paths that would be used to locate a simple filename with
|
|
.Fn dlopen .
|
|
For simplicity, error checking has been omitted.
|
|
.Bd -literal
|
|
Dl_serinfo _info, *info = &_info;
|
|
Dl_serpath *path;
|
|
unsigned int cnt;
|
|
|
|
/* determine search path count and required buffer size */
|
|
dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, (void *)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, (void *)info);
|
|
|
|
path = &info->dls_serpath[0];
|
|
|
|
for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) {
|
|
(void) printf("%2d: %s\n", cnt, path->dls_name);
|
|
}
|
|
.Ed
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn dlinfo
|
|
function returns 0 on success, or -1 if error occured.
|
|
Whenever an error has been detected, a message detailing it can
|
|
be retrieved via a call to
|
|
.Fn dlerror .
|
|
.Sh SEE ALSO
|
|
.Xr rtld 1 ,
|
|
.Xr dladdr 3 ,
|
|
.Xr dlopen 3 ,
|
|
.Xr dlsym 3
|
|
.Sh HISTORY
|
|
The
|
|
.Fn dlinfo
|
|
function first appeared in the Solaris operating system.
|
|
In
|
|
.Fx
|
|
it first appeared in
|
|
.Fx 4.8 .
|
|
.Sh AUTHORS
|
|
The
|
|
.Fx
|
|
implementation of
|
|
.Fn dlinfo
|
|
function was originally written by
|
|
.An Alexey Zelkin
|
|
.Aq phantom@FreeBSD.org
|
|
and later extended and improved by
|
|
.An Alexander Kabaev
|
|
.Aq kan@FreeBSD.org .
|
|
.Pp
|
|
The manual page for this function was written by
|
|
.An Alexey Zelkin
|
|
.Aq phantom@FreeBSD.org .
|