Debian Codegraph @

upstream/debian-unstable/man3/dlsym.3

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