man3/dladdr.3

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