Technical Reference: Base Operating System and Extensions, Volume 1

dladdr Subroutine

Purpose

Translates address to symbolic information.

Syntax

   #include <dlfcn.h>
 
   int dladdr(void *address, Dl_info *dlip);

Description

dladdr allows a process to obtain information about the symbol that most closely defines a given address. dladdr first determines whether the specified address is located within one of the mapped objects (executable or shared objects) that make up the process' address space. An address is deemed to fall within a mapped object when it is between the base address at which the object was mapped and the highest virtual address mapped for that object, inclusive. If a mapped object fits this criteria, its dynamic symbol table is searched to locate the nearest symbol to the specified address. The nearest symbol is the one whose value is equal to, or closest to but less than, the specified address.

dlip is a pointer to a Dl_info structure. The structure must be allocated by the user. The structure members are set by dladdr if the specified address falls within one of the mapped objects. The Dl_info structure contains at least the following members:

        const char      *dli_fname;
        void            *dli_fbase;
        const char      *dli_sname;
        void            *dli_saddr;
        size_t  dli_size;
        int             dli_bind;
        int             dli_type;

Descriptions of these members appear below:

dli_fname

Contains a pointer to the filename of the mapped object containing address.

dli_fbase

Contains the base address of the mapped object containing address.

dli_sname

Contains a pointer to the name of the nearest symbol to the specified address. This symbol either has the same address, or is the nearest symbol with a lower address.

dli_saddr

Contains the actual address of the nearest symbol.

dli_size

Contains the size of the nearest symbol as defined in the dynamic symbol table.

dli_bind

Contains the binding attribute of the nearest symbol as defined in the dynamic symbol table. The values are those used for a symbol's binding in the ELF symbol table [see <elf.h> and Symbol table]. in Object files in Programming in standard C and C++.

dli_type

Contains the type attribute of the nearest symbol as defined in the dynamic symbol table. The values are those used for a symbol's type in the ELF symbol table [see <elf.h> and Symbol table]. in Object files in Programming in standard C and C++.

If no symbol is found within the object containing address whose value is less than or equal to address, the dli_sname, dli_saddr and dli_size members are set to 0; the dli_bind member is set to STB_LOCAL, and the dli_type member is set to STT_NOTYPE.

For the a.out, the symbol table created by ld for use by the dynamic linker might contain only a subset of the symbols defined in the a.out [see dlopen (dlopen Subroutine)]. This could cause dladdr to return information for a symbol that is actually unrelated to the specified address.

The addresses and the strings pointed to by the members of the Dl_info structure refer to locations within mapped objects. These may become invalid if the objects are unmapped from the address space [see dlclose (dlclose Subroutine)]

Implementation Specifics

This subroutine is valid only on the Itanium-based platform.

Return values

If the specified address does not fall within one of the mapped objects, 0 is returned; the contents of the Dl_info structure are unspecified. Otherwise, a non-zero value is returned and the associated Dl_info elements are set.

Related Information

The dlclose (dlclose Subroutine) subroutine, dlerror (dlerror Subroutine) subroutine, dlopen (dlopen Subroutine) subroutine, and dlsym (dladdr Subroutine) subroutine.