Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
Dynamic Linking Library Functionsdlinfo(3DL)


NAME

 dlinfo - dynamic load information

SYNOPSIS

 
cc [ flag ... ] file ... -ldl [ library ... ]
#include <dlfcn.h>
#include <link.h>
#include <limits.h>
int dlinfo(void *handle, int request, void *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 TYPEATTRIBUTE VALUE
MT-LevelMT-Safe

SEE ALSO

 

ld(1), ioctl(2), dirname(3C), dlclose(3DL), dldump(3DL), dlerror(3DL), dlmopen(3DL), dlopen(3DL), dlsym(3DL), realpath(3C), attributes(5)

Linker and Libraries Guide


SunOS 5.9Go To TopLast Changed 11 Aug 2000

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.