dladdr(3C)

dladdr -- translate address to symbolic information

Synopsis

   
   #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 Programming in standard C and C++]. 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 Programming in standard C and C++]. in ``Object files'' in Programming in standard C and C++.

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.

References

dlclose(3C), dlerror(3C), dlopen(3C), dlsym(3C)

Notices

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(3C)]. 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(3C)]