NAME
dladdr() — get the symbolic information for an address
SYNOPSIS
cc
[flag]...
cfile ...
-ldl
[library]...
#include <dlfcn.h>
int dladdr(void *address, Dl_info *dlip);
Multithread Usage
This routine is thread-safe.
DESCRIPTION
dladdr()
is one of a family of routines that give the user
direct access to the dynamic linking facilities
(using the
-ldl
option on the compiler or
ld
command line).
dladdr()
allows a process to obtain information about the symbol that most
closely defines a given
address.
dladdr()
determines whether the specified
address
is located within one of the load modules (executable or shared
libraries) that make up the process' address space. An address is
deemed to fall within a load module when it is between the base
address at which the load module was mapped and the highest virtual
address mapped for that load module, inclusive.
If a load module 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 load modules.
The
Dl_info
structure contains the following members:
struct {
const char *dli_fname;
void *dli_fbase;
const char *dli_sname;
void *dli_saddr;
size_t dli_size; /* ELF only */
int dli_bind; /* ELF only */
int dli_type;
};
The fields of the
Dl_info
structure contain the following:
- dli_fname
Pointer to the filename of the load module containing
the
address.
The contents of this memory location can change between calls to
dladdr().
- dli_fbase
Handle to the load module. This can be used as the
first argument to
dlsym().
- dli_sname
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. The contents of this memory location can change
between calls to
dladdr().
- dli_saddr
Actual address of the nearest symbol. For code
symbols, it contains the address of the OPD (Official Plabel
Descriptor) for the nearest code symbol.
- dli_size
(ELF process only) Size of the nearest symbol as
defined in the dynamic symbol table.
- dli_bind
(ELF process only) Binding attribute of the nearest
symbol as defined in the dynamic symbol table. The values for this are
those used for a symbol's binding in the ELF symbol table (see
<elf.h>)
- dli_type
Type of the nearest symbol.
For ELF process, this is the same as the value for type in the dynamic
symbol table.
The values for this are those used for a symbol's type in the ELF
symbol table (see
<elf.h>).
For SOM process, this can have the value
TYPE_DATA
or
TYPE_PROCEDURE
as defined in
<dl.h>).
RETURN VALUE
If the specified
address
does not fall within one of the load modules,
0
is returned; the contents of the
Dl_info
structure are not modified. Otherwise, a non-zero value is returned and
the fields of the
Dl_info
structure are set.
DIAGNOSTICS
If no symbol is found within the load module containing
address
whose value is less than or equal to
address,
the
dli_sname,
dli_saddr,
and
dli_size
fields are set to
0;
the
dli_bind
field is set to
STB_LOCAL,
and the
dli_type
field is set to
STT_NOTYPE.
For
a.out's,
only a subset of externally visible symbols are typically exported:
specifically those referenced by the load modules with which the
a.out
is linked. The exact set of exported symbols for any shared library
or the
a.out
can be controlled using the linker (see
ld(1)).
ERRORS
If
dladdr()
fails, a subsequent call to
dlerrno()
returns one of the following values:
- RTLD_ERR_BAD_DLL
Invalid symbol address in load module.
- RTLD_ERR_CANT_APPLY_RELOC
Cannot apply relocation in library.
- RTLD_ERR_DLADDR_NOTFOUND
Address not found in any load module.
- RTLD_ERR_NO_MEMORY
Out of memory.
- RTLD_ERR_SETCANCELSTATE_FAILED
__thread_setcancelstate
failed on entry to or exit from
dladdr().
- RTLD_ERR_SIGENABLE_FAILED
sigenable
failed on exit from
dladdr().
- RTLD_ERR_SIGINHIBIT_FAILED
siginhibit
failed on entry to
dladdr().