1DLOPEN(3P) POSIX Programmer's Manual DLOPEN(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 dlopen - gain access to an executable object file
13
15 #include <dlfcn.h>
16 void *dlopen(const char *file, int mode);
18
21 The dlopen() function shall make an executable object file specified by
22 file available to the calling program. The class of files eligible for
23 this operation and the manner of their construction are implementation-
24 defined, though typically such files are executable objects such as
25 shared libraries, relocatable files, or programs. Note that some imple‐
26 mentations permit the construction of dependencies between such objects
27 that are embedded within files. In such cases, a dlopen() operation
28 shall load such dependencies in addition to the object referenced by
29 file. Implementations may also impose specific constraints on the con‐
30 struction of programs that can employ dlopen() and its related ser‐
31 vices.
32 A successful dlopen() shall return a handle which the caller may use on
34 subsequent calls to dlsym() and dlclose(). The value of this handle
35 should not be interpreted in any way by the caller.
36 The file argument is used to construct a pathname to the object file.
38 If file contains a slash character, the file argument is used as the
39 pathname for the file. Otherwise, file is used in an implementation-
40 defined manner to yield a pathname.
41 If the value of file is 0, dlopen() shall provide a handle on a global
43 symbol object. This object shall provide access to the symbols from an
44 ordered set of objects consisting of the original program image file,
45 together with any objects loaded at program start-up as specified by
46 that process image file (for example, shared libraries), and the set of
47 objects loaded using a dlopen() operation together with the RTLD_GLOBAL
48 flag. As the latter set of objects can change during execution, the set
49 identified by handle can also change dynamically.
50 Only a single copy of an object file is brought into the address space,
52 even if dlopen() is invoked multiple times in reference to the file,
53 and even if different pathnames are used to reference the file.
54 The mode parameter describes how dlopen() shall operate upon file with
56 respect to the processing of relocations and the scope of visibility of
57 the symbols provided within file. When an object is brought into the
58 address space of a process, it may contain references to symbols whose
59 addresses are not known until the object is loaded. These references
60 shall be relocated before the symbols can be accessed. The mode parame‐
61 ter governs when these relocations take place and may have the follow‐
62 ing values:
63 RTLD_LAZY
65 Relocations shall be performed at an implementation-defined
66 time, ranging from the time of the dlopen() call until the first
67 reference to a given symbol occurs. Specifying RTLD_LAZY should
68 improve performance on implementations supporting dynamic symbol
69 binding as a process may not reference all of the functions in
70 any given object. And, for systems supporting dynamic symbol
71 resolution for normal process execution, this behavior mimics
72 the normal handling of process execution.
73 RTLD_NOW
75 All necessary relocations shall be performed when the object is
76 first loaded. This may waste some processing if relocations are
77 performed for functions that are never referenced. This behavior
78 may be useful for applications that need to know as soon as an
79 object is loaded that all symbols referenced during execution
80 are available.
81 Any object loaded by dlopen() that requires relocations against global
84 symbols can reference the symbols in the original process image file,
85 any objects loaded at program start-up, from the object itself as well
86 as any other object included in the same dlopen() invocation, and any
87 objects that were loaded in any dlopen() invocation and which specified
88 the RTLD_GLOBAL flag. To determine the scope of visibility for the sym‐
89 bols loaded with a dlopen() invocation, the mode parameter should be a
90 bitwise-inclusive OR with one of the following values:
91 RTLD_GLOBAL
93 The object's symbols shall be made available for the relocation
94 processing of any other object. In addition, symbol lookup using
95 dlopen(0, mode) and an associated dlsym() allows objects loaded
96 with this mode to be searched.
97 RTLD_LOCAL
99 The object's symbols shall not be made available for the reloca‐
100 tion processing of any other object.
101 If neither RTLD_GLOBAL nor RTLD_LOCAL are specified, then an implemen‐
104 tation-defined default behavior shall be applied.
105 If a file is specified in multiple dlopen() invocations, mode is inter‐
107 preted at each invocation. Note, however, that once RTLD_NOW has been
108 specified all relocations shall have been completed rendering further
109 RTLD_NOW operations redundant and any further RTLD_LAZY operations
110 irrelevant. Similarly, note that once RTLD_GLOBAL has been specified
111 the object shall maintain the RTLD_GLOBAL status regardless of any pre‐
112 vious or future specification of RTLD_LOCAL, as long as the object
113 remains in the address space (see dlclose()).
114 Symbols introduced into a program through calls to dlopen() may be used
116 in relocation activities. Symbols so introduced may duplicate symbols
117 already defined by the program or previous dlopen() operations. To
118 resolve the ambiguities such a situation might present, the resolution
119 of a symbol reference to symbol definition is based on a symbol resolu‐
120 tion order. Two such resolution orders are defined: load or dependency
121 ordering. Load order establishes an ordering among symbol definitions,
122 such that the definition first loaded (including definitions from the
123 image file and any dependent objects loaded with it) has priority over
124 objects added later (via dlopen()). Load ordering is used in relocation
125 processing. Dependency ordering uses a breadth-first order starting
126 with a given object, then all of its dependencies, then any dependents
127 of those, iterating until all dependencies are satisfied. With the
128 exception of the global symbol object obtained via a dlopen() operation
129 on a file of 0, dependency ordering is used by the dlsym() function.
130 Load ordering is used in dlsym() operations upon the global symbol
131 object.
132 When an object is first made accessible via dlopen() it and its depen‐
134 dent objects are added in dependency order. Once all the objects are
135 added, relocations are performed using load order. Note that if an
136 object or its dependencies had been previously loaded, the load and
137 dependency orders may yield different resolutions.
138 The symbols introduced by dlopen() operations and available through
140 dlsym() are at a minimum those which are exported as symbols of global
141 scope by the object. Typically such symbols shall be those that were
142 specified in (for example) C source code as having extern linkage. The
143 precise manner in which an implementation constructs the set of
144 exported symbols for a dlopen() object is specified by that implementa‐
145 tion.
146
148 If file cannot be found, cannot be opened for reading, is not of an
149 appropriate object format for processing by dlopen(), or if an error
150 occurs during the process of loading file or relocating its symbolic
151 references, dlopen() shall return NULL. More detailed diagnostic infor‐
152 mation shall be available through dlerror().
153
155 No errors are defined.
156 The following sections are informative.
158
160 None.
161
163 None.
164
166 None.
167
169 None.
170
172 dlclose(), dlerror(), dlsym(), the Base Definitions volume of
173 IEEE Std 1003.1-2001, <dlfcn.h>
174
176 Portions of this text are reprinted and reproduced in electronic form
177 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
178 -- Portable Operating System Interface (POSIX), The Open Group Base
179 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
180 Electrical and Electronics Engineers, Inc and The Open Group. In the
181 event of any discrepancy between this version and the original IEEE and
182 The Open Group Standard, the original IEEE and The Open Group Standard
183 is the referee document. The original Standard can be obtained online
184 at http://www.opengroup.org/unix/online.html .
185IEEE/The Open Group 2003 DLOPEN(3P)