diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man3/dladdr.3')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man3/dladdr.3 | 276 |
1 files changed, 276 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man3/dladdr.3 b/upstream/opensuse-tumbleweed/man3/dladdr.3 new file mode 100644 index 00000000..4571e67d --- /dev/null +++ b/upstream/opensuse-tumbleweed/man3/dladdr.3 @@ -0,0 +1,276 @@ +'\" 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 2023-07-20 "Linux man-pages 6.05.01" +.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> +.PP +.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: +.PP +.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 +.PP +If no symbol matching +.I addr +could be found, then +.I dli_sname +and +.I dli_saddr +are set to NULL. +.PP +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. +.PP +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 +.sp 1 +.SH STANDARDS +GNU. +.SH HISTORY +.TP +.BR dladdr () +glibc 2.0. +.TP +.BR dladdr1 () +glibc 2.3.3. +.PP +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. +.PP +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) |