Content-type: text/html Man page of dlinfo

dlinfo

Section: Standard C Library Functions (3C)
Updated: 2 Jun 2005
Index Return to Main Contents
 

NAME

dlinfo - dynamic load information  

SYNOPSIS

#include <dlfcn.h>
#include <link.h>
#include <limits.h>

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 RTLD_SELF. A handle argument is required for all requests except RTLD_DI_CONFIGADDR, RTLD_DI_GETSIGNAL, and RTLD_DI_SETSIGNAL. 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 RTLD_SELF, the information returned by the dlinfo() call pertains to the caller.

The request argument can take the following values:

RTLD_DI_ARGSINFO

Obtain process argument information. The p argument is a pointer (Dl_argsinfo *p). The following elements from this structure are initialized:

dla_argc

The number of arguments passed to the process.

dla_argv

The argument array passed to the process.

dla_envp

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 alternative environment be established by the process. See putenv(3C).

dla_auxv

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 Dl_argsinfo information reflects the information that is made available to the application regardless of how the runtime linker has been invoked.

RTLD_DI_CONFIGADDR

Obtain the configuration file information. 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 that is 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 full name 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 can be examined by following the l_next and l_prev members.

l_prev

The previous Link_map on the link-map list.

l_refname

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.

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 that is 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 member points to the search path. The corresponding dlp_info member contains one of more flags indicating the origin of the path. See the LA_SER_* flags that are 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 members are returned. The dls_cnt member indicates the number of search paths that are applicable to the handle. The dls_size member indicates 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. This new buffer should be initialized with the dls_cnt and dls_size entries. The initialized buffer is then passed to a RTLD_DI_SERINFO request. See EXAMPLES.

RTLD_DI_ORIGIN

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

RTLD_DI_GETSIGNAL

Obtain the numeric signal number used by the runtime linker to kill the process in the event of a fatal runtime 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 SIGKILL. See thr_kill(3C). This default can be changed by calling dlinfo() with RTLD_DI_SETSIGNAL or by setting the environment variable LD_SIGNAL. See ld.so.1(1).

RTLD_DI_SETSIGNAL

Provide a numeric signal number used by the runtime linker to kill the process in the event of a fatal runtime error. The p argument is an int pointer (int *p). The value pointed to by p is established as the terminating signal value.

The current signal number used by the runtime linker to terminate a process can be obtained from dlinfo() using RTLD_DI_GETSIGNAL. Use of the RTLD_DI_SETSIGNAL option is equivalent to setting the environment variable LD_SIGNAL. See ld.so.1(1).

 

RETURN VALUES

The dlinfo() function returns -1 if the request is invalid, the parameter p is NULL, or the Dl_serinfo structure is uninitialized for a RTLD_DI_SERINFO 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 RTLD_SELF. Detailed diagnostic information is available with dlerror(3C).  

EXAMPLES

Example 1: Use dlinfo() to obtain the 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.

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. These facilities are available to dynamically-linked processes only. See the Linker and Libraries Guide.  

ATTRIBUTES

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

ATTRIBUTE TYPEATTRIBUTE VALUE
Interface StabilityStable
MT-LevelMT-Safe

 

SEE ALSO

ld(1), ld.so.1(1), exec(2), ioctl(2), dirname(3C), dlclose(3C), dldump(3C), dlerror(3C), dlopen(3C), dlsym(3C), putenv(3C), realpath(3C), thr_kill(3C), attributes(5).

Linker and Libraries Guide


 

Index

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUES
EXAMPLES
USAGE
ATTRIBUTES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 02:37:18 GMT, October 02, 2010