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
13 dlsym — get the address of a symbol from a symbol table handle
14
16 #include <dlfcn.h>
17 void *dlsym(void *restrict handle, const char *restrict name);
19
21 The dlsym() function shall obtain the address of a symbol (a function
22 identifier or a data object identifier) defined in the symbol table
23 identified by the handle argument. The handle argument is a symbol ta‐
24 ble handle returned from a call to dlopen() (and which has not since
25 been released by a call to dlclose()), and name is the symbol's name as
26 a character string. The return value from dlsym(), cast to a pointer to
27 the type of the named symbol, can be used to call (in the case of a
28 function) or access the contents of (in the case of a data object) the
29 named symbol.
30 The dlsym() function shall search for the named symbol in the symbol
32 table referenced by handle. If the symbol table was created with lazy
33 loading (see RTLD_LAZY in dlopen()), load ordering shall be used in
34 dlsym() operations to relocate executable object files needed to
35 resolve the symbol. The symbol resolution algorithm used shall be
36 dependency order as described in dlopen().
37 The RTLD_DEFAULT and RTLD_NEXT symbolic constants (which may be defined
39 in <dlfcn.h>) are reserved for future use as special values that appli‐
40 cations may be allowed to use for handle.
41
43 Upon successful completion, if name names a function identifier,
44 dlsym() shall return the address of the function converted from type
45 pointer to function to type pointer to void; otherwise, dlsym() shall
46 return the address of the data object associated with the data object
47 identifier named by name converted from a pointer to the type of the
48 data object to a pointer to void. If handle does not refer to a valid
49 symbol table handle or if the symbol named by name cannot be found in
50 the symbol table associated with handle, dlsym() shall return a null
51 pointer.
52 More detailed diagnostic information shall be available through dler‐
54 ror().
55
57 No errors are defined.
58 The following sections are informative.
60
62 The following example shows how dlopen() and dlsym() can be used to
63 access either a function or a data object. For simplicity, error check‐
64 ing has been omitted.
65 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");
110 is not defined by the ISO C standard. This standard requires this con‐
112 version to work correctly on conforming implementations.
113
115 None.
116
118 None.
119
121 dlclose(), dlerror(), dlopen()
122 The Base Definitions volume of POSIX.1‐2008, <dlfcn.h>
124
126 Portions of this text are reprinted and reproduced in electronic form
127 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
128 -- Portable Operating System Interface (POSIX), The Open Group Base
129 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
130 cal and Electronics Engineers, Inc and The Open Group. (This is
131 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/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 2013 DLSYM(3P)