1 .\" This source code is a product of Sun Microsystems, Inc. and is provided
2 .\" for unrestricted use provided that this legend is included on all tape
3 .\" media and as a part of the software program in whole or part. Users
4 .\" may copy or modify this source code without charge, but are not authorized
5 .\" to license or distribute it to anyone else except as part of a product or
6 .\" program developed by the user.
8 .\" THIS PROGRAM CONTAINS SOURCE CODE COPYRIGHTED BY SUN MICROSYSTEMS, INC.
9 .\" SUN MICROSYSTEMS, INC., MAKES NO REPRESENTATIONS ABOUT THE SUITABLITY
10 .\" OF SUCH SOURCE CODE FOR ANY PURPOSE. IT IS PROVIDED "AS IS" WITHOUT
11 .\" EXPRESS OR IMPLIED WARRANTY OF ANY KIND. SUN MICROSYSTEMS, INC. DISCLAIMS
12 .\" ALL WARRANTIES WITH REGARD TO SUCH SOURCE CODE, INCLUDING ALL IMPLIED
13 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN
14 .\" NO EVENT SHALL SUN MICROSYSTEMS, INC. BE LIABLE FOR ANY SPECIAL, INDIRECT,
15 .\" INCIDENTAL, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
16 .\" FROM USE OF SUCH SOURCE CODE, REGARDLESS OF THE THEORY OF LIABILITY.
18 .\" This source code is provided with no support and without any obligation on
19 .\" the part of Sun Microsystems, Inc. to assist in its use, correction,
20 .\" modification or enhancement.
22 .\" SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
23 .\" INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS
24 .\" SOURCE CODE OR ANY PART THEREOF.
26 .\" Sun Microsystems, Inc.
27 .\" 2550 Garcia Avenue
28 .\" Mountain View, California 94043
30 .\" Copyright (c) 1991 Sun Microsystems, Inc.
32 .\" @(#) dlopen.3 1.6 90/01/31 SMI
45 .Nd programmatic interface to the dynamic linker
51 .Fn dlopen "const char *path" "int mode"
53 .Fn fdlopen "int fd" "int mode"
55 .Fn dlsym "void * restrict handle" "const char * restrict symbol"
57 .Fn dlfunc "void * restrict handle" "const char * restrict symbol"
61 .Fn dlclose "void *handle"
63 These functions provide a simple programmatic interface to the services of the
65 Operations are provided to add new shared objects to a
66 program's address space, to obtain the address bindings of symbols
68 objects, and to remove such objects when their use is no longer required.
73 provides access to the shared object in
75 returning a descriptor that can be used for later
76 references to the object in calls to
82 was not in the address space prior to the call to
84 it is placed in the address space.
85 When an object is first loaded into the address space in this way, its
88 if any, is called by the dynamic linker.
91 has already been placed in the address space in a previous call to
93 it is not added a second time, although a reference count of
98 A null pointer supplied for
100 is interpreted as a reference to the main
101 executable of the process.
105 controls the way in which external function references from the
106 loaded object are bound to their referents.
107 It must contain one of the following values, possibly ORed with
108 additional flags which will be described subsequently:
109 .Bl -tag -width RTLD_LAZYX
111 Each external function reference is resolved when the function is first
114 All external function references are bound immediately by
119 is normally preferred, for reasons of efficiency.
122 is useful to ensure that any undefined symbols are discovered during the
126 One of the following flags may be ORed into the
129 .Bl -tag -width RTLD_NODELETE
131 Symbols from this shared object and its directed acyclic graph (DAG)
132 of needed objects will be available for resolving undefined references
133 from all other shared objects.
135 Symbols in this shared object and its DAG of needed objects will be
136 available for resolving undefined references only from other objects
138 This is the default, but it may be specified
139 explicitly with this flag.
141 When set, causes dynamic linker to exit after loading all objects
142 needed by this shared object and printing a summary which includes
143 the absolute pathnames of all objects, to standard output.
146 will return to the caller only in the case of error.
148 Prevents unload of the loaded object on
150 The same behaviour may be requested by
152 option of the static linker
155 Only return valid handle for the object if it is already loaded in
156 the process address space, otherwise
159 Other mode flags may be specified, which will be applied for promotion
160 for the found object.
165 fails, it returns a null pointer, and sets an error condition which may
171 function is similar to
173 but it takes the file descriptor argument
175 which is used for the file operations needed to load an object
176 into the address space.
179 is not closed by the function regardless a result of execution,
180 but a duplicate of the file descriptor is.
181 This may be important if a
183 lock is held on the passed descriptor.
186 argument -1 is interpreted as a reference to the main
187 executable of the process, similar to
195 function can be used by the code that needs to perform
196 additional checks on the loaded objects, to prevent races with
197 symlinking or renames.
202 returns the address binding of the symbol described in the null-terminated
205 as it occurs in the shared object identified by
207 The symbols exported by objects added to the address space by
209 can be accessed only through calls to
211 Such symbols do not supersede any definition of those symbols already present
212 in the address space when the object is loaded, nor are they available to
213 satisfy normal dynamic linking references.
217 is called with the special
220 it is interpreted as a reference to the executable or shared object
223 Thus a shared object can reference its own symbols.
227 is called with the special
230 the search for the symbol follows the algorithm used for resolving
231 undefined symbols when objects are loaded.
232 The objects searched are
233 as follows, in the given order:
236 The referencing object itself (or the object from which the call to
238 is made), if that object was linked using the
243 All objects loaded at program start-up.
245 All objects loaded via
253 All objects loaded via
255 which are in needed-object DAGs that also contain the referencing object.
260 is called with the special
263 then the search for the symbol is limited to the shared objects
264 which were loaded after the one issuing the call to
266 Thus, if the function is called from the main program, all
267 the shared libraries are searched.
268 If it is called from a shared library, all subsequent shared
269 libraries are searched.
271 is useful for implementing wrappers around library functions.
272 For example, a wrapper function
278 .Li dlsym(RTLD_NEXT, \&"getpid\&") .
281 interface, below, should be used, since
283 is a function and not a data object.)
287 is called with the special
290 then the search for the symbol is limited to the shared object
293 and those shared objects which were loaded after it.
298 returns a null pointer if the symbol cannot be found, and sets an error
299 condition which may be queried with
305 implements all of the behavior of
307 but has a return type which can be cast to a function pointer without
308 triggering compiler diagnostics.
312 returns a data pointer; in the C standard, conversions between
313 data and function pointer types are undefined.
316 utilities warn about such casts.)
317 The precise return type of
319 is unspecified; applications must cast it to an appropriate function pointer
325 returns a null-terminated character string describing the last error that
326 occurred during a call to
334 If no such error has occurred,
336 returns a null pointer.
339 the error indication is reset.
340 Thus in the case of two calls
343 where the second call follows the first immediately, the second call
344 will always return a null pointer.
349 deletes a reference to the shared object referenced by
351 If the reference count drops to 0, the object is removed from the
355 Just before removing a shared object in this way, the dynamic linker
358 function, if such a function is defined by the object.
361 is successful, it returns a value of 0.
362 Otherwise it returns -1, and sets an error condition that can be
366 The object-intrinsic functions
370 are called with no arguments, and are not expected to return values.
372 ELF executables need to be linked
377 for symbols defined in the executable to become visible to
380 In previous implementations, it was necessary to prepend an underscore
381 to all external symbols in order to gain symbol
382 compatibility with object code compiled from the C language.
384 still the case when using the (obsolete)
386 option to the C language compiler.
395 return a null pointer in the event of errors.
399 returns 0 on success, or -1 if an error occurred.
400 Whenever an error has been detected, a message detailing it can be
401 retrieved via a call to