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 2015-08-08 "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
  35 .BI "int dladdr(void *" addr ", Dl_info *" info );
  36
  37 .BI "int dladdr1(void *" addr ", Dl_info *" info ", void **" \
  38         extra_info ", int " flags );
  39
  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 .sp
  56 .in +4n
  57 .nf
  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 .fi
  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
  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
 101 .in +4n
 102 .nf
 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 .fi
 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
 138 .in +4n
 139 .nf
 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 .fi
 149 .in
 150
 151 The
 152 .I st_name
 153 field is an index into the string table.
 154
 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
 187 .in +4n
 188 .TS
 189 lb lb
 190 lb l.
 191 Value   Description
 192 STB_LOCAL       Local symbol
 193 STB_GLOBAL      Global symbol
 194 STB_WEAK        Weak symbol
 195 STB_GNU_UNIQUE  Unique symbol
 196 .TE
 197 .in
 198 .IP
 199 The
 200 .I st_other
 201 field contains the symbol's visibility, which can be extracted using the macro
 202 .BR ELF64_ST_VISIBILITY(st_info)
 203 (or
 204 .BR ELF32_ST_VISIBILITY()
 205 on 32-bit platforms), which yields one of the following values:
 206 .in +4n
 207 .TS
 208 lb lb
 209 lb l.
 210 Value   Description
 211 STV_DEFAULT     Default symbol visibility rules
 212 STV_INTERNAL    Processor-specific hidden class
 213 STV_HIDDEN      Symbol unavailable in other modules
 214 STV_PROTECTED   Not preemptible, not exported
 215 .TE
 216 .in
 217 .SH RETURN VALUE
 218 On success, these functions return a nonzero value.
 219 If the address specified in
 220 .I addr
 221 could be matched to a shared object,
 222 but not to a symbol in the shared object, then the
 223 .I info->dli_sname
 224 and
 225 .I info->dli_saddr
 226 fields are set to NULL.
 227
 228
 229 If the address specified in
 230 .I addr
 231 could not be matched to a shared object, then these functions return 0.
 232 In this case, an error message is
 233 .I not
 234 .\" According to the FreeBSD man page, dladdr1() does signal an
 235 .\" error via dlerror() for this case.
 236 available via
 237 .BR dlerror (3).
 238 .SH VERSIONS
 239 .BR dladdr ()
 240 is present in glibc 2.0 and later.
 241 .BR dladdr1 ()
 242 first appeared in glibc 2.3.3.
 243 .SH ATTRIBUTES
 244 For an explanation of the terms used in this section, see
 245 .BR attributes (7).
 246 .TS
 247 allbox;
 248 lbw19 lb lb
 249 l l l.
 250 Interface       Attribute       Value
 251 T{
 252 .BR dladdr (),
 253 .BR dladdr1 ()
 254 T}      Thread safety   MT-Safe
 255 .TE
 256 .SH CONFORMING TO
 257 These functions are nonstandard GNU extensions
 258 that are also present on Solaris.
 259 .SH BUGS
 260 Sometimes, the function pointers you pass to
 261 .BR dladdr ()
 262 may surprise you.
 263 On some architectures (notably i386 and x86_64),
 264 .I dli_fname
 265 and
 266 .I dli_fbase
 267 may end up pointing back at the object from which you called
 268 .BR dladdr (),
 269 even if the function used as an argument should come from
 270 a dynamically linked library.
 271 .PP
 272 The problem is that the function pointer will still be resolved
 273 at compile time, but merely point to the
 274 .I plt
 275 (Procedure Linkage Table)
 276 section of the original object (which dispatches the call after
 277 asking the dynamic linker to resolve the symbol).
 278 To work around this,
 279 you can try to compile the code to be position-independent:
 280 then, the compiler cannot prepare the pointer
 281 at compile time any more and
 282 .BR gcc (1)
 283 will generate code that just loads the final symbol address from the
 284 .I got
 285 (Global Offset Table) at run time before passing it to
 286 .BR dladdr ().
 287 .SH SEE ALSO
 288 .BR dl_iterate_phdr (3),
 289 .BR dlinfo (3),
 290 .BR dlopen (3),
 291 .BR dlsym (3),
 292 .BR ld.so (8)