summaryrefslogtreecommitdiffstats
path: root/man/man3/dladdr.3
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-24 04:52:22 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-24 04:52:22 +0000
commit3d08cd331c1adcf0d917392f7e527b3f00511748 (patch)
tree312f0d1e1632f48862f044b8bb87e602dcffb5f9 /man/man3/dladdr.3
parentAdding debian version 6.7-2. (diff)
downloadmanpages-3d08cd331c1adcf0d917392f7e527b3f00511748.tar.xz
manpages-3d08cd331c1adcf0d917392f7e527b3f00511748.zip
Merging upstream version 6.8.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man/man3/dladdr.3')
-rw-r--r--man/man3/dladdr.3275
1 files changed, 275 insertions, 0 deletions
diff --git a/man/man3/dladdr.3 b/man/man3/dladdr.3
new file mode 100644
index 0000000..889f60a
--- /dev/null
+++ b/man/man3/dladdr.3
@@ -0,0 +1,275 @@
+'\" 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 2024-05-02 "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)