:man| Alphabetical   Categories   About us 
 
DLINFO (3) | C library functions | Unix Manual Pages | :man▋

NAME

dlinfo - information about dynamically loaded object

CONTENTS

Library
Synopsis
Description
Return Values
Examples
See Also
History
Authors

LIBRARY


.Lb libc

SYNOPSIS


.In link.h
.In dlfcn.h int dlinfo "void * restrict handle" "int request" "void * restrict p"

DESCRIPTION

The dlinfo function provides information about dynamically loaded object. The action taken by dlinfo and exact meaning and type of p argument depend on value of the request argument provided by caller.

The handle argument is either the value returned from the dlopen(3) function call or special handle RTLD_SELF. If handle is the value returned from dlopen(3), the information returned by the dlinfo function pertains to the specified object. If handle is the special handle RTLD_SELF, the information returned pertains to the caller itself.

Possible values for the request argument are:

RTLD_DI_LINKMAP
Retrieve the
.Vt Link_map (Vt "struct link_map") structure pointer for the specified handle. On successful return, the p argument is filled with the pointer to the
.Vt Link_map structure ("Link_map **p") describing a shared object specified by the handle argument. The
.Vt Link_map structures are maintained as a doubly linked list by ld.so(1), in the same order as dlopen(3) and dlclose(3) are called. See EXAMPLES, example 1.

The
.Vt Link_map structure is defined in
.In link.h and has the following members:
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 mapped libs */
*l_prev;

l_addr The base address of the object loaded into memory.
l_name The full name of the loaded shared object.
l_ld The address of the dynamic linking information segment (PT_DYNAMIC) loaded into memory.
l_next The next
.Vt Link_map structure on the link-map list.
l_prev The previous
.Vt Link_map structure on the link-map list.
RTLD_DI_SERINFO
Retrieve the library search paths associated with the given handle argument. The p argument should point to
.Vt Dl_serinfo structure buffer ("Dl_serinfo *p"). The
.Vt Dl_serinfo structure must be initialized first with the RTLD_DI_SERINFOSIZE request.

The returned
.Vt Dl_serinfo structure contains dls_cnt
.Vt Dl_serpath entries. Each entry’s dlp_name field points to the search path. The corresponding dlp_info field contains one of more flags indicating the origin of the path (see the LA_SER_* flags defined in the
.In link.h header file). See EXAMPLES, example 2, for a usage example.

RTLD_DI_SERINFOSIZE
Initialize a
.Vt Dl_serinfo structure for use in a RTLD_DI_SERINFO request. Both the dls_cnt and dls_size fields are returned to indicate the number of search paths applicable to the handle, and the total size of a
.Vt Dl_serinfo buffer required to hold dls_cnt
.Vt Dl_serpath entries and the associated search path strings. See EXAMPLES, example 2, for a usage example.
RTLD_DI_ORIGIN
Retrieve the origin of the dynamic object associated with the handle. On successful return, p argument is filled with the
.Vt char pointer ("char *p").

RETURN VALUES

The dlinfo function returns 0 on success, or -1 if an error occurred. Whenever an error has been detected, a message detailing it can be retrieved via a call to dlerror(3).

EXAMPLES

Example 1: Using dlinfo to retrieve
.Vt Link_map structure.

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.
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;
}

Example 2: Using dlinfo to retrieve the library search paths.

The following example shows how a dynamic object can inspect the library search paths that would be used to locate a simple filename with dlopen(3). For simplicity, error checking has been omitted.
Dl_serinfo _info, *info = &_info;
Dl_serpath *path;
unsigned intcnt;


/* 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);
}

SEE ALSO

rtld(1), dladdr(3), dlopen(3), dlsym(3)

HISTORY

AUTHORS

 
Created by Blin Media, 2008-2013