dlsym(3) - f39

1dlsym(3)                   Library Functions Manual                   dlsym(3)
2
3
4

NAME

6       dlsym,  dlvsym  - obtain address of a symbol in a shared object or exe‐
7       cutable
8

LIBRARY

10       Dynamic linking library (libdl, -ldl)
11

SYNOPSIS

13       #include <dlfcn.h>
14
15       void *dlsym(void *restrict handle, const char *restrict symbol);
16
17       #define _GNU_SOURCE
18       #include <dlfcn.h>
19
20       void *dlvsym(void *restrict handle, const char *restrict symbol,
21                    const char *restrict version);
22

DESCRIPTION

24       The function dlsym() takes a "handle" of a dynamic loaded shared object
25       returned by dlopen(3) along with a null-terminated symbol name, and re‐
26       turns the address where that symbol is loaded into memory.  If the sym‐
27       bol  is not found, in the specified object or any of the shared objects
28       that were automatically  loaded  by  dlopen(3)  when  that  object  was
29       loaded,  dlsym()  returns  NULL.   (The  search performed by dlsym() is
30       breadth first through the dependency tree of these shared objects.)
31
32       In unusual cases (see NOTES) the value of the symbol could actually  be
33       NULL.   Therefore,  a NULL return from dlsym() need not indicate an er‐
34       ror.  The correct way to distinguish an error from a symbol whose value
35       is  NULL  is to call dlerror(3) to clear any old error conditions, then
36       call dlsym(), and then call dlerror(3) again, saving its  return  value
37       into a variable, and check whether this saved value is not NULL.
38
39       There are two special pseudo-handles that may be specified in handle:
40
41       RTLD_DEFAULT
42              Find  the  first  occurrence of the desired symbol using the de‐
43              fault shared object  search  order.   The  search  will  include
44              global  symbols  in the executable and its dependencies, as well
45              as symbols in shared objects that were dynamically  loaded  with
46              the RTLD_GLOBAL flag.
47
48       RTLD_NEXT
49              Find the next occurrence of the desired symbol in the search or‐
50              der after the current object.  This  allows  one  to  provide  a
51              wrapper around a function in another shared object, so that, for
52              example, the definition of a function in a preloaded shared  ob‐
53              ject (see LD_PRELOAD in ld.so(8)) can find and invoke the "real"
54              function provided in another shared object (or for that  matter,
55              the  "next"  definition of the function in cases where there are
56              multiple layers of preloading).
57
58       The _GNU_SOURCE feature test macro must be defined in order  to  obtain
59       the definitions of RTLD_DEFAULT and RTLD_NEXT from <dlfcn.h>.
60
61       The  function  dlvsym()  does  the  same as dlsym() but takes a version
62       string as an additional argument.
63

RETURN VALUE

65       On success, these functions return the address associated with  symbol.
66       On  failure,  they return NULL; the cause of the error can be diagnosed
67       using dlerror(3).
68

ATTRIBUTES

70       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
71       tributes(7).
72
73       ┌────────────────────────────────────────────┬───────────────┬─────────┐
74       │Interface                                   │ Attribute     │ Value   │
75       ├────────────────────────────────────────────┼───────────────┼─────────┤
76       │dlsym(), dlvsym()                           │ Thread safety │ MT-Safe │
77       └────────────────────────────────────────────┴───────────────┴─────────┘
78

STANDARDS

80       dlsym()
81              POSIX.1-2008.
82
83       dlvsym()
84              GNU.
85

HISTORY

87       dlsym()
88              glibc 2.0.  POSIX.1-2001.
89
90       dlvsym()
91              glibc 2.1.
92

NOTES

94       There  are  several  scenarios  when  the address of a global symbol is
95       NULL.  For example, a symbol can be  placed  at  zero  address  by  the
96       linker,  via  a  linker  script  or  with --defsym command-line option.
97       Undefined weak symbols also have NULL value.  Finally, the symbol value
98       may  be the result of a GNU indirect function (IFUNC) resolver function
99       that returns NULL as the resolved value.  In the latter  case,  dlsym()
100       also returns NULL without error.  However, in the former two cases, the
101       behavior of GNU dynamic linker is inconsistent:  relocation  processing
102       succeeds and the symbol can be observed to have NULL value, but dlsym()
103       fails and dlerror() indicates a lookup error.
104
105   History
106       The dlsym() function is part of the dlopen  API,  derived  from  SunOS.
107       That system does not have dlvsym().
108

EXAMPLES

110       See dlopen(3).
111