man3/dlsym.3

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