man3/dlsym.3

   1 .\" Copyright 1995 Yggdrasil Computing, Incorporated.
   2 .\" and Copyright 2003, 2015 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH DLSYM 3 2019-03-06 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 dlsym, dlvsym \- obtain address of a symbol in a shared object or executable
  28 .SH SYNOPSIS
  29 .B #include <dlfcn.h>
  30 .PP
  31 .BI "void *dlsym(void *" handle ", const char *" symbol );
  32 .PP
  33 .B #define _GNU_SOURCE
  34 .br
  35 .B #include <dlfcn.h>
  36 .PP
  37 .BI "void *dlvsym(void *" handle ", char *" symbol ", char *" version );
  38 .PP
  39 Link with \fI\-ldl\fP.
  40 .SH DESCRIPTION
  41 The function
  42 .BR dlsym ()
  43 takes a "handle" of a dynamic loaded shared object returned by
  44 .BR dlopen (3)
  45 along with a null-terminated symbol name,
  46 and returns the address where that symbol is
  47 loaded into memory.
  48 If the symbol is not found, in the specified
  49 object or any of the shared objects that were automatically loaded by
  50 .BR dlopen (3)
  51 when that object was loaded,
  52 .BR dlsym ()
  53 returns NULL.
  54 (The search performed by
  55 .BR dlsym ()
  56 is breadth first through the dependency tree of these shared objects.)
  57 .PP
  58 In unusual cases (see NOTES) the value of the symbol could actually be NULL.
  59 Therefore, a NULL return from
  60 .BR dlsym ()
  61 need not indicate an error.
  62 The correct way to distinguish an error from a symbol whose value is NULL
  63 is to call
  64 .BR dlerror (3)
  65 to clear any old error conditions, then call
  66 .BR dlsym (),
  67 and then call
  68 .BR dlerror (3)
  69 again, saving its return value into a variable, and check whether
  70 this saved value is not NULL.
  71 .PP
  72 There are two special pseudo-handles that may be specified in
  73 .IR handle :
  74 .TP
  75 .B RTLD_DEFAULT
  76 Find the first occurrence of the desired symbol
  77 using the default shared object search order.
  78 The search will include global symbols in the executable
  79 and its dependencies,
  80 as well as symbols in shared objects that were dynamically loaded with the
  81 .BR RTLD_GLOBAL
  82 flag.
  83 .TP
  84 .BR RTLD_NEXT
  85 Find the next occurrence of the desired symbol in the search order
  86 after the current object.
  87 This allows one to provide a wrapper
  88 around a function in another shared object, so that, for example,
  89 the definition of a function in a preloaded shared object
  90 (see
  91 .B LD_PRELOAD
  92 in
  93 .BR ld.so (8))
  94 can find and invoke the "real" function provided in another shared object
  95 (or for that matter, the "next" definition of the function in cases
  96 where there are multiple layers of preloading).
  97 .PP
  98 The
  99 .B _GNU_SOURCE
 100 feature test macro must be defined in order to obtain the
 101 definitions of
 102 .B RTLD_DEFAULT
 103 and
 104 .B RTLD_NEXT
 105 from
 106 .IR <dlfcn.h> .
 107 .PP
 108 .PP
 109 The function
 110 .BR dlvsym ()
 111 does the same as
 112 .BR dlsym ()
 113 but takes a version string as an additional argument.
 114 .SH RETURN VALUE
 115 On success,
 116 these functions return the address associated with
 117 .IR symbol .
 118 On failure, they return NULL;
 119 the cause of the error can be diagnosed using
 120 .BR dlerror (3).
 121 .SH VERSIONS
 122 .BR dlsym ()
 123 is present in glibc 2.0 and later.
 124 .BR dlvsym ()
 125 first appeared in glibc 2.1.
 126 .SH ATTRIBUTES
 127 For an explanation of the terms used in this section, see
 128 .BR attributes (7).
 129 .TS
 130 allbox;
 131 lb lb lb
 132 l l l.
 133 Interface       Attribute       Value
 134 T{
 135 .BR dlsym (),
 136 .BR dlvsym ()
 137 T}      Thread safety   MT-Safe
 138 .TE
 139 .SH CONFORMING TO
 140 POSIX.1-2001 describes
 141 .BR dlsym ().
 142 The
 143 .BR dlvsym ()
 144 function is a GNU extension.
 145 .SH NOTES
 146 There are several scenarios when the address of a global symbol is NULL.
 147 For example, a symbol can be placed at zero address by the linker, via
 148 a linker script or with
 149 .I --defsym
 150 command-line option. Undefined weak symbols also have NULL value.
 151 Finally, the symbol value may be the result of
 152 a GNU indirect function (IFUNC) resolver function that returns
 153 NULL as the resolved value. In the latter case,
 154 .BR dlsym ()
 155 also returns NULL without error. However, in the former two cases, the
 156 behavior of GNU dynamic linker is inconsistent: relocation processing
 157 succeeds and the symbol can be observed to have NULL value, but
 158 .BR dlsym ()
 159 fails and
 160 .BR dlerror ()
 161 indicates a lookup error.
 162 .\"
 163 .SS History
 164 The
 165 .BR dlsym ()
 166 function is part of the dlopen API, derived from SunOS.
 167 That system does not have
 168 .BR dlvsym ().
 169 .SH EXAMPLE
 170 See
 171 .BR dlopen (3).
 172 .SH SEE ALSO
 173 .BR dl_iterate_phdr (3),
 174 .BR dladdr (3),
 175 .BR dlerror (3),
 176 .BR dlinfo (3),
 177 .BR dlopen (3),
 178 .BR ld.so (8)