+++ /dev/null
-'\" t
-.\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com>
-.\" and Copyright (C) 2008 Petr Baudis <pasky@suse.cz> (dladdr caveat)
-.\"
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
-.\"
-.TH dladdr 3 (date) "Linux man-pages (unreleased)"
-.SH NAME
-dladdr, dladdr1 \- translate address to symbolic information
-.SH LIBRARY
-Dynamic linking library
-.RI ( libdl ", " \-ldl )
-.SH SYNOPSIS
-.nf
-.B #define _GNU_SOURCE
-.B #include <dlfcn.h>
-.P
-.BI "int dladdr(const void *" addr ", Dl_info *" info );
-.BI "int dladdr1(const void *" addr ", Dl_info *" info ", void **" extra_info ,
-.BI " int " flags );
-.fi
-.SH DESCRIPTION
-The function
-.BR dladdr ()
-determines whether the address specified in
-.I addr
-is located in one of the shared objects loaded by the calling application.
-If it is, then
-.BR dladdr ()
-returns information about the shared object and symbol that overlaps
-.IR addr .
-This information is returned in a
-.I Dl_info
-structure:
-.P
-.in +4n
-.EX
-typedef struct {
- const char *dli_fname; /* Pathname of shared object that
- contains address */
- void *dli_fbase; /* Base address at which shared
- object is loaded */
- const char *dli_sname; /* Name of symbol whose definition
- overlaps \fIaddr\fP */
- void *dli_saddr; /* Exact address of symbol named
- in \fIdli_sname\fP */
-} Dl_info;
-.EE
-.in
-.P
-If no symbol matching
-.I addr
-could be found, then
-.I dli_sname
-and
-.I dli_saddr
-are set to NULL.
-.P
-The function
-.BR dladdr1 ()
-is like
-.BR dladdr (),
-but returns additional information via the argument
-.IR extra_info .
-The information returned depends on the value specified in
-.IR flags ,
-which can have one of the following values:
-.TP
-.B RTLD_DL_LINKMAP
-Obtain a pointer to the link map for the matched file.
-The
-.I extra_info
-argument points to a pointer to a
-.I link_map
-structure (i.e.,
-.IR "struct link_map\~**" ),
-defined in
-.I <link.h>
-as:
-.IP
-.in +4n
-.EX
-struct link_map {
- ElfW(Addr) l_addr; /* Difference between the
- address in the ELF file and
- the address in memory */
- char *l_name; /* Absolute pathname where
- object was found */
- ElfW(Dyn) *l_ld; /* Dynamic section of the
- shared object */
- struct link_map *l_next, *l_prev;
- /* Chain of loaded objects */
-\&
- /* Plus additional fields private to the
- implementation */
-};
-.EE
-.in
-.TP
-.B RTLD_DL_SYMENT
-Obtain a pointer to the ELF symbol table entry of the matching symbol.
-The
-.I extra_info
-argument is a pointer to a symbol pointer:
-.IR "const ElfW(Sym) **" .
-The
-.IR ElfW ()
-macro definition turns its argument into the name of an ELF data
-type suitable for the hardware architecture.
-For example, on a 64-bit platform,
-.I ElfW(Sym)
-yields the data type name
-.IR Elf64_Sym ,
-which is defined in
-.I <elf.h>
-as:
-.IP
-.in +4n
-.EX
-typedef struct {
- Elf64_Word st_name; /* Symbol name */
- unsigned char st_info; /* Symbol type and binding */
- unsigned char st_other; /* Symbol visibility */
- Elf64_Section st_shndx; /* Section index */
- Elf64_Addr st_value; /* Symbol value */
- Elf64_Xword st_size; /* Symbol size */
-} Elf64_Sym;
-.EE
-.in
-.IP
-The
-.I st_name
-field is an index into the string table.
-.IP
-The
-.I st_info
-field encodes the symbol's type and binding.
-The type can be extracted using the macro
-.B ELF64_ST_TYPE(st_info)
-(or
-.B ELF32_ST_TYPE()
-on 32-bit platforms), which yields one of the following values:
-.in +4n
-.TS
-lb lb
-lb l.
-Value Description
-STT_NOTYPE Symbol type is unspecified
-STT_OBJECT Symbol is a data object
-STT_FUNC Symbol is a code object
-STT_SECTION Symbol associated with a section
-STT_FILE Symbol's name is filename
-STT_COMMON Symbol is a common data object
-STT_TLS Symbol is thread-local data object
-STT_GNU_IFUNC Symbol is indirect code object
-.TE
-.in
-.IP
-The symbol binding can be extracted from the
-.I st_info
-field using the macro
-.B ELF64_ST_BIND(st_info)
-(or
-.B ELF32_ST_BIND()
-on 32-bit platforms), which yields one of the following values:
-.in +4n
-.TS
-lb lb
-lb l.
-Value Description
-STB_LOCAL Local symbol
-STB_GLOBAL Global symbol
-STB_WEAK Weak symbol
-STB_GNU_UNIQUE Unique symbol
-.TE
-.in
-.IP
-The
-.I st_other
-field contains the symbol's visibility, which can be extracted using the macro
-.B ELF64_ST_VISIBILITY(st_info)
-(or
-.B ELF32_ST_VISIBILITY()
-on 32-bit platforms), which yields one of the following values:
-.in +4n
-.TS
-lb lb
-lb l.
-Value Description
-STV_DEFAULT Default symbol visibility rules
-STV_INTERNAL Processor-specific hidden class
-STV_HIDDEN Symbol unavailable in other modules
-STV_PROTECTED Not preemptible, not exported
-.TE
-.in
-.SH RETURN VALUE
-On success, these functions return a nonzero value.
-If the address specified in
-.I addr
-could be matched to a shared object,
-but not to a symbol in the shared object, then the
-.I info\->dli_sname
-and
-.I info\->dli_saddr
-fields are set to NULL.
-.P
-If the address specified in
-.I addr
-could not be matched to a shared object, then these functions return 0.
-In this case, an error message is
-.I not
-.\" According to the FreeBSD man page, dladdr1() does signal an
-.\" error via dlerror() for this case.
-available via
-.BR dlerror (3).
-.SH ATTRIBUTES
-For an explanation of the terms used in this section, see
-.BR attributes (7).
-.TS
-allbox;
-lbx lb lb
-l l l.
-Interface Attribute Value
-T{
-.na
-.nh
-.BR dladdr (),
-.BR dladdr1 ()
-T} Thread safety MT-Safe
-.TE
-.SH STANDARDS
-GNU.
-.SH HISTORY
-.TP
-.BR dladdr ()
-glibc 2.0.
-.TP
-.BR dladdr1 ()
-glibc 2.3.3.
-.P
-Solaris.
-.SH BUGS
-Sometimes, the function pointers you pass to
-.BR dladdr ()
-may surprise you.
-On some architectures (notably i386 and x86-64),
-.I dli_fname
-and
-.I dli_fbase
-may end up pointing back at the object from which you called
-.BR dladdr (),
-even if the function used as an argument should come from
-a dynamically linked library.
-.P
-The problem is that the function pointer will still be resolved
-at compile time, but merely point to the
-.I plt
-(Procedure Linkage Table)
-section of the original object (which dispatches the call after
-asking the dynamic linker to resolve the symbol).
-To work around this,
-you can try to compile the code to be position-independent:
-then, the compiler cannot prepare the pointer
-at compile time any more and
-.BR gcc (1)
-will generate code that just loads the final symbol address from the
-.I got
-(Global Offset Table) at run time before passing it to
-.BR dladdr ().
-.SH SEE ALSO
-.BR dl_iterate_phdr (3),
-.BR dlinfo (3),
-.BR dlopen (3),
-.BR dlsym (3),
-.BR ld.so (8)
projects / thirdparty / man-pages.git / blobdiff