man3/dladdr.3

   1 .\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" and Copyright (C) 2008 Petr Baudis <pasky@suse.cz> (dladdr caveat)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH DLADDR 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
   7 .SH NAME
   8 dladdr, dladdr1 \- translate address to symbolic information
   9 .SH LIBRARY
  10 Dynamic linking library
  11 .RI ( libdl ", " \-ldl )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #define _GNU_SOURCE
  15 .B #include <dlfcn.h>
  16 .PP
  17 .BI "int dladdr(const void *" addr ", Dl_info *" info );
  18 .BI "int dladdr1(const void *" addr ", Dl_info *" info ", void **" extra_info ,
  19 .BI "            int " flags );
  20 .fi
  21 .SH DESCRIPTION
  22 The function
  23 .BR dladdr ()
  24 determines whether the address specified in
  25 .I addr
  26 is located in one of the shared objects loaded by the calling application.
  27 If it is, then
  28 .BR dladdr ()
  29 returns information about the shared object and symbol that overlaps
  30 .IR addr .
  31 This information is returned in a
  32 .I Dl_info
  33 structure:
  34 .PP
  35 .in +4n
  36 .EX
  37 typedef struct {
  38     const char *dli_fname;  /* Pathname of shared object that
  39                                contains address */
  40     void       *dli_fbase;  /* Base address at which shared
  41                                object is loaded */
  42     const char *dli_sname;  /* Name of symbol whose definition
  43                                overlaps \fIaddr\fP */
  44     void       *dli_saddr;  /* Exact address of symbol named
  45                                in \fIdli_sname\fP */
  46 } Dl_info;
  47 .EE
  48 .in
  49 .PP
  50 If no symbol matching
  51 .I addr
  52 could be found, then
  53 .I dli_sname
  54 and
  55 .I dli_saddr
  56 are set to NULL.
  57 .PP
  58 The function
  59 .BR dladdr1 ()
  60 is like
  61 .BR dladdr (),
  62 but returns additional information via the argument
  63 .IR extra_info .
  64 The information returned depends on the value specified in
  65 .IR flags ,
  66 which can have one of the following values:
  67 .TP
  68 .B RTLD_DL_LINKMAP
  69 Obtain a pointer to the link map for the matched file.
  70 The
  71 .I extra_info
  72 argument points to a pointer to a
  73 .I link_map
  74 structure (i.e.,
  75 .IR "struct link_map\~**" ),
  76 defined in
  77 .I <link.h>
  78 as:
  79 .IP
  80 .in +4n
  81 .EX
  82 struct link_map {
  83     ElfW(Addr) l_addr;  /* Difference between the
  84                            address in the ELF file and
  85                            the address in memory */
  86     char      *l_name;  /* Absolute pathname where
  87                            object was found */
  88     ElfW(Dyn) *l_ld;    /* Dynamic section of the
  89                            shared object */
  90     struct link_map *l_next, *l_prev;
  91                         /* Chain of loaded objects */
  92
  93     /* Plus additional fields private to the
  94        implementation */
  95 };
  96 .EE
  97 .in
  98 .TP
  99 .B RTLD_DL_SYMENT
 100 Obtain a pointer to the ELF symbol table entry of the matching symbol.
 101 The
 102 .I extra_info
 103 argument is a pointer to a symbol pointer:
 104 .IR "const ElfW(Sym) **" .
 105 The
 106 .IR ElfW ()
 107 macro definition turns its argument into the name of an ELF data
 108 type suitable for the hardware architecture.
 109 For example, on a 64-bit platform,
 110 .I ElfW(Sym)
 111 yields the data type name
 112 .IR Elf64_Sym ,
 113 which is defined in
 114 .I <elf.h>
 115 as:
 116 .IP
 117 .in +4n
 118 .EX
 119 typedef struct  {
 120     Elf64_Word    st_name;     /* Symbol name */
 121     unsigned char st_info;     /* Symbol type and binding */
 122     unsigned char st_other;    /* Symbol visibility */
 123     Elf64_Section st_shndx;    /* Section index */
 124     Elf64_Addr    st_value;    /* Symbol value */
 125     Elf64_Xword   st_size;     /* Symbol size */
 126 } Elf64_Sym;
 127 .EE
 128 .in
 129 .IP
 130 The
 131 .I st_name
 132 field is an index into the string table.
 133 .IP
 134 The
 135 .I st_info
 136 field encodes the symbol's type and binding.
 137 The type can be extracted using the macro
 138 .B ELF64_ST_TYPE(st_info)
 139 (or
 140 .B ELF32_ST_TYPE()
 141 on 32-bit platforms), which yields one of the following values:
 142 .in +4n
 143 .TS
 144 lb lb
 145 lb l.
 146 Value   Description
 147 STT_NOTYPE      Symbol type is unspecified
 148 STT_OBJECT      Symbol is a data object
 149 STT_FUNC        Symbol is a code object
 150 STT_SECTION     Symbol associated with a section
 151 STT_FILE        Symbol's name is filename
 152 STT_COMMON      Symbol is a common data object
 153 STT_TLS Symbol is thread-local data object
 154 STT_GNU_IFUNC   Symbol is indirect code object
 155 .TE
 156 .in
 157 .IP
 158 The symbol binding can be extracted from the
 159 .I st_info
 160 field using the macro
 161 .B ELF64_ST_BIND(st_info)
 162 (or
 163 .B ELF32_ST_BIND()
 164 on 32-bit platforms), which yields one of the following values:
 165 .in +4n
 166 .TS
 167 lb lb
 168 lb l.
 169 Value   Description
 170 STB_LOCAL       Local symbol
 171 STB_GLOBAL      Global symbol
 172 STB_WEAK        Weak symbol
 173 STB_GNU_UNIQUE  Unique symbol
 174 .TE
 175 .in
 176 .IP
 177 The
 178 .I st_other
 179 field contains the symbol's visibility, which can be extracted using the macro
 180 .B ELF64_ST_VISIBILITY(st_info)
 181 (or
 182 .B ELF32_ST_VISIBILITY()
 183 on 32-bit platforms), which yields one of the following values:
 184 .in +4n
 185 .TS
 186 lb lb
 187 lb l.
 188 Value   Description
 189 STV_DEFAULT     Default symbol visibility rules
 190 STV_INTERNAL    Processor-specific hidden class
 191 STV_HIDDEN      Symbol unavailable in other modules
 192 STV_PROTECTED   Not preemptible, not exported
 193 .TE
 194 .in
 195 .SH RETURN VALUE
 196 On success, these functions return a nonzero value.
 197 If the address specified in
 198 .I addr
 199 could be matched to a shared object,
 200 but not to a symbol in the shared object, then the
 201 .I info\->dli_sname
 202 and
 203 .I info\->dli_saddr
 204 fields are set to NULL.
 205 .PP
 206 If the address specified in
 207 .I addr
 208 could not be matched to a shared object, then these functions return 0.
 209 In this case, an error message is
 210 .I not
 211 .\" According to the FreeBSD man page, dladdr1() does signal an
 212 .\" error via dlerror() for this case.
 213 available via
 214 .BR dlerror (3).
 215 .SH VERSIONS
 216 .BR dladdr ()
 217 is present in glibc 2.0 and later.
 218 .BR dladdr1 ()
 219 first appeared in glibc 2.3.3.
 220 .SH ATTRIBUTES
 221 For an explanation of the terms used in this section, see
 222 .BR attributes (7).
 223 .ad l
 224 .nh
 225 .TS
 226 allbox;
 227 lbx lb lb
 228 l l l.
 229 Interface       Attribute       Value
 230 T{
 231 .BR dladdr (),
 232 .BR dladdr1 ()
 233 T}      Thread safety   MT-Safe
 234 .TE
 235 .hy
 236 .ad
 237 .sp 1
 238 .SH STANDARDS
 239 These functions are nonstandard GNU extensions
 240 that are also present on Solaris.
 241 .SH BUGS
 242 Sometimes, the function pointers you pass to
 243 .BR dladdr ()
 244 may surprise you.
 245 On some architectures (notably i386 and x86-64),
 246 .I dli_fname
 247 and
 248 .I dli_fbase
 249 may end up pointing back at the object from which you called
 250 .BR dladdr (),
 251 even if the function used as an argument should come from
 252 a dynamically linked library.
 253 .PP
 254 The problem is that the function pointer will still be resolved
 255 at compile time, but merely point to the
 256 .I plt
 257 (Procedure Linkage Table)
 258 section of the original object (which dispatches the call after
 259 asking the dynamic linker to resolve the symbol).
 260 To work around this,
 261 you can try to compile the code to be position-independent:
 262 then, the compiler cannot prepare the pointer
 263 at compile time any more and
 264 .BR gcc (1)
 265 will generate code that just loads the final symbol address from the
 266 .I got
 267 (Global Offset Table) at run time before passing it to
 268 .BR dladdr ().
 269 .SH SEE ALSO
 270 .BR dl_iterate_phdr (3),
 271 .BR dlinfo (3),
 272 .BR dlopen (3),
 273 .BR dlsym (3),
 274 .BR ld.so (8)