1dlsym(3C)                Standard C Library Functions                dlsym(3C)
2
3
4

NAME

6       dlsym - get the address of a symbol in a shared object or executable
7

SYNOPSIS

9       #include <dlfcn.h>
10
11       void *dlsym(void *restrict handle, const char *restrict name);
12
13

DESCRIPTION

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
21
22       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
30
31       The following special handles are supported.
32
33       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
41                       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
49
50       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
61
62       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
66
67       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
71
72
73       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
77           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
82           o      The  object  has  global search access. See dlopen(3C) for a
83                  discussion of the RTLD_GLOBAL mode.
84

RETURN VALUES

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

EXAMPLES

93       Example 1 Use dlopen()  and  dlsym()  to  access  a  function  or  data
94       objects.
95
96
97       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
101
102         void      *handle;
103         int       *iptr, (*fptr)(int);
104
105         /* open the needed object */
106         handle = dlopen("/usr/home/me/libfoo.so.1", RTLD_LAZY);
107
108         /* find the address of function and data objects */
109         fptr = (int (*)(int))dlsym(handle, "my_function");
110         iptr = (int *)dlsym(handle, "my_object");
111
112         /* invoke function, passing value of integer as a parameter */
113         (*fptr)(*iptr);
114
115
116       Example 2 Use dlsym() to verify that a particular function is defined.
117
118
119       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
122
123         int (*fptr)();
124
125         if ((fptr = (int (*)())dlsym(RTLD_DEFAULT,
126             "my_function")) != NULL) {
127                 (*fptr)();
128         }
129
130

USAGE

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

ATTRIBUTES

138       See attributes(5) for descriptions of the following attributes:
139
140
141
142
143       ┌─────────────────────────────┬─────────────────────────────┐
144       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
145       ├─────────────────────────────┼─────────────────────────────┤
146       │Interface Stability          │Standard                     │
147       ├─────────────────────────────┼─────────────────────────────┤
148       │MT-Level                     │MT-Safe                      │
149       └─────────────────────────────┴─────────────────────────────┘
150

SEE ALSO

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
155
156       Linker and Libraries Guide
157

NOTES

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.
165
166
167
168SunOS 5.11                        26 Sep 2005                        dlsym(3C)
Impressum