1DLSYM(3P) POSIX Programmer's Manual DLSYM(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 dlsym — get the address of a symbol from a symbol table handle
13
15 #include <dlfcn.h>
16 void *dlsym(void *restrict handle, const char *restrict name);
18
20 The dlsym() function shall obtain the address of a symbol (a function
21 identifier or a data object identifier) defined in the symbol table
22 identified by the handle argument. The handle argument is a symbol ta‐
23 ble handle returned from a call to dlopen() (and which has not since
24 been released by a call to dlclose()), and name is the symbol's name as
25 a character string. The return value from dlsym(), cast to a pointer to
26 the type of the named symbol, can be used to call (in the case of a
27 function) or access the contents of (in the case of a data object) the
28 named symbol.
29 The dlsym() function shall search for the named symbol in the symbol
31 table referenced by handle. If the symbol table was created with lazy
32 loading (see RTLD_LAZY in dlopen()), load ordering shall be used in
33 dlsym() operations to relocate executable object files needed to
34 resolve the symbol. The symbol resolution algorithm used shall be
35 dependency order as described in dlopen().
36 The RTLD_DEFAULT and RTLD_NEXT symbolic constants (which may be defined
38 in <dlfcn.h>) are reserved for future use as special values that appli‐
39 cations may be allowed to use for handle.
40
42 Upon successful completion, if name names a function identifier,
43 dlsym() shall return the address of the function converted from type
44 pointer to function to type pointer to void; otherwise, dlsym() shall
45 return the address of the data object associated with the data object
46 identifier named by name converted from a pointer to the type of the
47 data object to a pointer to void. If handle does not refer to a valid
48 symbol table handle or if the symbol named by name cannot be found in
49 the symbol table associated with handle, dlsym() shall return a null
50 pointer.
51 More detailed diagnostic information shall be available through dler‐
53 ror().
54
56 No errors are defined.
57 The following sections are informative.
59
61 The following example shows how dlopen() and dlsym() can be used to
62 access either a function or a data object. For simplicity, error check‐
63 ing has been omitted.
64 void *handle;
67 int (*fptr)(int), *iptr, result;
68 /* open the needed symbol table */
69 handle = dlopen("/usr/home/me/libfoo.so", RTLD_LOCAL | RTLD_LAZY);
70 /* find the address of the function my_function */
71 fptr = (int (*)(int))dlsym(handle, "my_function");
72 /* find the address of the data object my_object */
73 iptr = (int *)dlsym(handle, "my_OBJ");
74 /* invoke my_function, passing the value of my_OBJ as the parameter */
75 result = (*fptr)(*iptr);
76
78 The following special purpose values for handle are reserved for future
79 use and have the indicated meanings:
80 RTLD_DEFAULT
82 The identifier lookup happens in the normal global scope;
83 that is, a search for an identifier using handle would find
84 the same definition as a direct use of this identifier in
85 the program code.
86 RTLD_NEXT Specifies the next executable object file after this one
88 that defines name. This one refers to the executable
89 object file containing the invocation of dlsym(). The next
90 executable object file is the one found upon the applica‐
91 tion of a load order symbol resolution algorithm (see
92 dlopen()). The next symbol is either one of global scope
93 (because it was introduced as part of the original process
94 image or because it was added with a dlopen() operation
95 including the RTLD_GLOBAL flag), or is in an executable
96 object file that was included in the same dlopen() opera‐
97 tion that loaded this one.
98 The RTLD_NEXT flag is useful to navigate an intentionally created hier‐
100 archy of multiply-defined symbols created through interposition. For
101 example, if a program wished to create an implementation of malloc()
102 that embedded some statistics gathering about memory allocations, such
103 an implementation could use the real malloc() definition to perform the
104 memory allocation — and itself only embed the necessary logic to imple‐
105 ment the statistics gathering function.
106 Note that conversion from a void * pointer to a function pointer as in:
108 fptr = (int (*)(int))dlsym(handle, "my_function");
111 is not defined by the ISO C standard. This standard requires this con‐
113 version to work correctly on conforming implementations.
114
116 None.
117
119 None.
120
122 dlclose(), dlerror(), dlopen()
123 The Base Definitions volume of POSIX.1‐2017, <dlfcn.h>
125
127 Portions of this text are reprinted and reproduced in electronic form
128 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
129 table Operating System Interface (POSIX), The Open Group Base Specifi‐
130 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
131 Electrical and Electronics Engineers, Inc and The Open Group. In the
132 event of any discrepancy between this version and the original IEEE and
133 The Open Group Standard, the original IEEE and The Open Group Standard
134 is the referee document. The original Standard can be obtained online
135 at http://www.opengroup.org/unix/online.html .
136 Any typographical or formatting errors that appear in this page are
138 most likely to have been introduced during the conversion of the source
139 files to man page format. To report such errors, see https://www.ker‐
140 nel.org/doc/man-pages/reporting_bugs.html .
141IEEE/The Open Group 2017 DLSYM(3P)