| '\" t |
| .\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" and Copyright (C) 2008 Petr Baudis <pasky@suse.cz> (dladdr caveat) |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH DLADDR 3 2015-08-08 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| dladdr, dladdr1 \- translate address to symbolic information |
| .SH SYNOPSIS |
| .nf |
| .B #define _GNU_SOURCE |
| .B #include <dlfcn.h> |
| |
| .BI "int dladdr(void *" addr ", Dl_info *" info ); |
| |
| .BI "int dladdr1(void *" addr ", Dl_info *" info ", void **" \ |
| extra_info ", int " flags ); |
| |
| Link with \fI\-ldl\fP. |
| .fi |
| .SH DESCRIPTION |
| The function |
| .BR dladdr () |
| determines whether the address specified in |
| .IR 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: |
| .sp |
| .in +4n |
| .nf |
| 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; |
| .fi |
| .in |
| .PP |
| If no symbol matching |
| .I addr |
| could be found, then |
| .I dli_sname |
| and |
| .I dli_saddr |
| are set to NULL. |
| |
| 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 |
| .IR 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: |
| |
| .in +4n |
| .nf |
| 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 */ |
| }; |
| .fi |
| .in |
| .TP |
| .B RTLD_DL_SYMENT |
| Obtain a pointer to the ELF symbol table entry of the matching symbol. |
| The |
| .IR 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 |
| .IR <elf.h> |
| as: |
| |
| .in +4n |
| .nf |
| 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; |
| .fi |
| .in |
| |
| The |
| .I st_name |
| field is an index into the string table. |
| |
| The |
| .I st_info |
| field encodes the symbol's type and binding. |
| The type can be extracted using the macro |
| .BR ELF64_ST_TYPE(st_info) |
| (or |
| .BR 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 file name |
| 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 |
| .BR ELF64_ST_BIND(st_info) |
| (or |
| .BR 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 |
| .BR ELF64_ST_VISIBILITY(st_info) |
| (or |
| .BR 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. |
| |
| 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 VERSIONS |
| .BR dladdr () |
| is present in glibc 2.0 and later. |
| .BR dladdr1 () |
| first appeared in glibc 2.3.3. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .TS |
| allbox; |
| lbw19 lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR dladdr (), |
| .BR dladdr1 () |
| T} Thread safety MT-Safe |
| .TE |
| .SH CONFORMING TO |
| These functions are nonstandard GNU extensions |
| that are also present on 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) |