dlinfo(3DL) (man pages section 3: Basic Library Functions)

man pages section 3: Basic Library Functions

dlinfo(3DL)

NAME

dlinfo– dynamic load information

SYNOPSIS

cc [ flag ... ] file ... -ldl [ library ... ]
#include <dlfcn.h>
#include <link.h>
#include <limits.h>

handle

request

p

DESCRIPTION

The dlinfo() function extracts information about a dynamically-loaded object. This function is loosely modeled after the ioctl() 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 provided.

A handle argument, required for all requests except RTLD_DI_CONFIGADDR, is either the value returned from a dlopen() or dlmopen() call, or the special handle RTLD_SELF. If handle is the value 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 RTLD_SELF, the information returned by the dlinfo() call pertains to the caller itself.

The following are possible values for request to be passed into dlinfo():

RTLD_DI_CONFIGADDR

Obtain the configuration file name and the address at which it has been loaded. The p argument is a Dl_info pointer ( Dl_info *p). The following elements from this structure are initialized:

dli_fname: The full name of the configuration file.
dli_fbase: The base address of the configuration file loaded into memory.

RTLD_DI_LINKMAP

Obtain the Link_map for the handle specified. The p argument points to a Link_map pointer ( Link_map **p ). The actual storage for the Link_map structure is maintained by ld.so.1.

The Link_map structure includes the following members:

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 */

l_addr: The base address of the object loaded into memory.
l_name: The full name of the loaded object. This is the filename of the object as referenced by ld.so.1.
l_ld: Points to the SHT_DYNAMIC structure.
l_next: The next Link_map on the link-map list, other objects on the same link-map list as the current object may be examined by following the and l_prev fields.
l_prev: The previous Link_map on the link-map list.
l_refname: If the object referenced is a filter this field points to the name of the object being filtered. If the object is not a filter, this field will be 0. See Linker and Libraries Guide.

RTLD_DI_LMID

Obtain the ID for the link-map list upon which the handle is loaded. The p argument is a Lmid_t pointer ( Lmid_t *p).

RTLD_DI_SERINFO

Obtain the library search paths for the handle specified. The p argument is a Dl_serinfo pointer ( Dl_serinfo *p). A user must first initialize the Dl_serinfo structure with a RTLD_DI_SERINFOSIZE request. See EXAMPLES.

The returned Dl_serinfo structure contains dls_cnt 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 <link.h>).

RTLD_DI_SERINFOSIZE

Initialize a 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 Dl_serinfo buffer required to hold dls_cnt Dl_serpath entries and the associated search path strings.

To obtain the complete path information, a new Dl_serinfo buffer of size dls_size should be allocated, initialized with the dls_cnt and dls_size entries, and passed to a RTLD_DI_SERINFO request. See EXAMPLES.

RTLD_DI_ORIGIN

Obtain the origin of the dynamic object 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 bigger than PATH_MAX, is copied to the pointer p.

RETURN VALUES

If the request is invalid, the parameter p is null, handle does not refer to a valid object opened by dlopen() or is not the special handle RTLD_SELF, or the Dl_serinfo structure is uninitialized for a RTLD_DI_SERINFO request, then dlinfo() returns -1. More detailed diagnostic information is available through dlerror(3DL).

EXAMPLES

Example 1 Using `dlinfo()` to obtain 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(). For simplicity, error checking has been omitted.

Dl_serinfo     _info, *info = &_info;
Dl_serpath     *path;
uint_t         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);
}

USAGE

The dlinfo() function is one of a family of functions that give the user direct access to the dynamic linking facilities (see Linker and Libraries Guide) and are available to dynamically-linked processes only.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe