Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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)