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 .PP
  17 .BI "void *dlsym(void *restrict " handle ", const char *restrict " symbol );
  18 .PP
  19 .B #define _GNU_SOURCE
  20 .B #include <dlfcn.h>
  21 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 VERSIONS
 106 .BR dlsym ()
 107 is present in glibc 2.0 and later.
 108 .BR dlvsym ()
 109 first appeared in glibc 2.1.
 110 .SH ATTRIBUTES
 111 For an explanation of the terms used in this section, see
 112 .BR attributes (7).
 113 .ad l
 114 .nh
 115 .TS
 116 allbox;
 117 lbx lb lb
 118 l l l.
 119 Interface       Attribute       Value
 120 T{
 121 .BR dlsym (),
 122 .BR dlvsym ()
 123 T}      Thread safety   MT-Safe
 124 .TE
 125 .hy
 126 .ad
 127 .sp 1
 128 .SH STANDARDS
 129 POSIX.1-2001 describes
 130 .BR dlsym ().
 131 The
 132 .BR dlvsym ()
 133 function is a GNU extension.
 134 .SH NOTES
 135 There are several scenarios when the address of a global symbol is NULL.
 136 For example, a symbol can be placed at zero address by the linker, via
 137 a linker script or with
 138 .I \-\-defsym
 139 command-line option.
 140 Undefined weak symbols also have NULL value.
 141 Finally, the symbol value may be the result of
 142 a GNU indirect function (IFUNC) resolver function that returns
 143 NULL as the resolved value.
 144 In the latter case,
 145 .BR dlsym ()
 146 also returns NULL without error.
 147 However, in the former two cases, the
 148 behavior of GNU dynamic linker is inconsistent: relocation processing
 149 succeeds and the symbol can be observed to have NULL value, but
 150 .BR dlsym ()
 151 fails and
 152 .BR dlerror ()
 153 indicates a lookup error.
 154 .\"
 155 .SS History
 156 The
 157 .BR dlsym ()
 158 function is part of the dlopen API, derived from SunOS.
 159 That system does not have
 160 .BR dlvsym ().
 161 .SH EXAMPLES
 162 See
 163 .BR dlopen (3).
 164 .SH SEE ALSO
 165 .BR dl_iterate_phdr (3),
 166 .BR dladdr (3),
 167 .BR dlerror (3),
 168 .BR dlinfo (3),
 169 .BR dlopen (3),
 170 .BR ld.so (8)