1dlsym(3C) Standard C Library Functions dlsym(3C)
2
6 dlsym - get the address of a symbol in a shared object or executable
7
9 #include <dlfcn.h>
10 void *dlsym(void *restrict handle, const char *restrict name);
12
15 The dlsym() function allows a process to obtain the address of a symbol
16 that is defined within a shared object or executable. The handle argu‐
17 ment is either the value returned from a call to dlopen() or one of a
18 family of special handles. The name argument is the symbol's name as a
19 character string.
20 If handle is returned from dlopen(), the associated shared object must
23 not have been closed using dlclose(). A handle can be obtained from
24 dlopen() using the RTLD_FIRST mode. With this mode, the dlsym() func‐
25 tion searches for the named symbol in the initial object referenced by
26 handle. Without this mode, the dlsym() function searches for the named
27 symbol in the group of shared objects loaded automatically as a result
28 of loading the object referenced by handle. See dlopen(3C) and NOTES.
29 The following special handles are supported.
32 RTLD_DEFAULT Instructs dlsym() to search for the named symbol start‐
34 ing with the first object loaded, typically the dynamic
35 executable. The search continues through the list of
36 initial dependencies that are loaded with the process,
37 followed by any objects obtained with dlopen(3C). This
38 search follows the default model that is used to relo‐
39 cate all objects within the process.
40 This model also provides for transitioning into a lazy
42 loading environment. If a symbol can not be found in
43 the presently loaded objects, any pending lazy loaded
44 objects are processed in an attempt to locate the sym‐
45 bol. This loading compensates for objects that have not
46 fully defined their dependencies. However, this compen‐
47 sation can undermine the advantages of lazy loading.
48 RTLD_PROBE Instructs dlsym() to search for the named symbol in the
51 same manner as occurs with a handle of RTLD_DEFAULT.
52 However, this model only searches for symbols in the
53 presently loaded objects, together with any lazy load‐
54 able objects specifically identified by the caller to
55 provide the named symbol. This handle does not trigger
56 an exhaustive load of any lazy loadable symbols in an
57 attempt to find the named symbol. This handle can pro‐
58 vide a more optimal search than would occur using
59 RTLD_DEFAULT.
60 RTLD_NEXT Instructs dlsym() to search for the named symbol in the
63 objects that were loaded following the object from
64 which the dlsym() call is being made.
65 RTLD_SELF Instructs dlsym() to search for the named symbol in the
68 objects that were loaded starting with the object from
69 which the dlsym() call is being made.
70 When used with a special handle, dlsym() is selective in searching
74 objects that have been loaded using dlopen(). These objects are
75 searched for symbols if one of the following conditions are true.
76 o The object is part of the same local dlopen() dependency
78 hierarchy as the calling object. See the Linker and
79 Libraries Guide for a description of dlopen() dependency
80 hierarchies.
81 o The object has global search access. See dlopen(3C) for a
83 discussion of the RTLD_GLOBAL mode.
84
86 The dlsym() function returns NULL if handle does not refer to a valid
87 object opened by dlopen() or is not one of the special handles. The
88 function also returns NULL if the named symbol cannot be found within
89 any of the objects associated with handle. Additional diagnostic infor‐
90 mation is available through dlerror(3C).
91
93 Example 1 Use dlopen() and dlsym() to access a function or data
94 objects.
95 The following code fragment demonstrates how to use dlopen() and
98 dlsym() to access either function or data objects. For simplicity,
99 error checking has been omitted.
100 void *handle;
103 int *iptr, (*fptr)(int);
104 /* open the needed object */
106 handle = dlopen("/usr/home/me/libfoo.so.1", RTLD_LAZY);
107 /* find the address of function and data objects */
109 fptr = (int (*)(int))dlsym(handle, "my_function");
110 iptr = (int *)dlsym(handle, "my_object");
111 /* invoke function, passing value of integer as a parameter */
113 (*fptr)(*iptr);
114 Example 2 Use dlsym() to verify that a particular function is defined.
117 The following code fragment shows how to use dlsym() to verify that a
120 function is defined. If the function exists, the function is called.
121 int (*fptr)();
124 if ((fptr = (int (*)())dlsym(RTLD_DEFAULT,
126 "my_function")) != NULL) {
127 (*fptr)();
128 }
129
132 The dlsym() function is one of a family of functions that give the user
133 direct access to the dynamic linking facilities. These facilities are
134 available to dynamically-linked processes only. See the Linker and
135 Libraries Guide.
136
138 See attributes(5) for descriptions of the following attributes:
139 ┌─────────────────────────────┬─────────────────────────────┐
144 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
145 ├─────────────────────────────┼─────────────────────────────┤
146 │Interface Stability │Standard │
147 ├─────────────────────────────┼─────────────────────────────┤
148 │MT-Level │MT-Safe │
149 └─────────────────────────────┴─────────────────────────────┘
150
152 ld(1), ld.so.1(1), dladdr(3C), dlclose(3C), dldump(3C), dlerror(3C),
153 dlinfo(3C), dlopen(3C), attributes(5), standards(5)
154 Linker and Libraries Guide
157
159 If an object is acting as a filter, care should be taken when inter‐
160 preting the address of any symbol obtained using a handle to this
161 object. For example, using dlsym(3C) to obtain the symbol _end for this
162 object, results in returning the address of the symbol _end within the
163 filtee, not the filter. For more information on filters see the Linker
164 and Libraries Guide.
165SunOS 5.11 26 Sep 2005 dlsym(3C)