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
35 .Dd September 24, 1989
39 .Nm dlopen, dlsym, dlerror, dlclose
40 .Nd programmatic interface to the dynamic linker
42 .Fd #include <dlfcn.h>
44 .Fn dlopen "const char *path" "int mode"
46 .Fn dlsym "void *handle" "const char *symbol"
50 .Fn dlclose "void *handle"
52 These functions provide a simple programmatic interface to the services of the
54 Operations are provided to add new shared objects to a
55 program's address space, to obtain the address bindings of symbols
57 objects, and to remove such objects when their use is no longer required.
60 provides access to the shared object in
62 returning a descriptor that can be used for later
63 references to the object in calls to
69 was not in the address space prior to the call to
71 it is placed in the address space.
72 When an object is first loaded into the address space in this way, its
75 if any, is called by the dynamic linker.
78 is the name as expressed in the C language.
79 From assembly language, the name would appear as
84 has already been placed in the address space in a previous call to
86 it is not added a second time, although a reference count of
91 A null pointer supplied for
93 is interpreted as a reference to the main
94 executable of the process.
96 controls the way in which external function references from the
97 loaded object are bound to their referents.
98 It must contain one of the following values:
99 .Bl -tag -width RTLD_LAZYX
101 Each external function reference is resolved when the function is first
104 All external function references are bound immediately by
109 is normally preferred, for reasons of efficiency.
112 is useful to ensure that any undefined symbols are discovered during the
117 fails, it returns a null pointer, and sets an error condition which may
122 returns the address binding of the symbol described in the null-terminated
125 as it occurs in the shared object identified by
129 is the assembly language representation of the symbol name.
130 The assembly language representation of a C language symbol contains an
131 extra underscore at the beginning.
132 For example, the symbol
136 in assembly language, and in the
140 The symbols exported by objects added to the address space by
142 can be accessed only through calls to
144 Such symbols do not supersede any definition of those symbols already present
145 in the address space when the object is loaded, nor are they available to
146 satisfy normal dynamic linking references.
147 A null pointer supplied as the value of
149 is interpreted as a reference to the executable from which the call to
151 is being made. Thus a shared object can reference its own symbols.
153 returns a null pointer if the symbol cannot be found, and sets an error
154 condition which may be queried with
159 is called with the special
162 then the search for the symbol is limited to the shared objects
163 which were loaded after the one issuing the call to
165 Thus, if the function is called from the main program, all
166 the shared libraries are searched.
167 If it is called from a shared library, all subsequent shared
168 libraries are searched.
170 is useful for implementing wrappers around library functions.
171 For example, a wrapper function
177 .Li dlsym(RTLD_NEXT, \&"_getpid\&") .
180 returns a null-terminated character string describing the last error that
181 occurred during a call to
186 If no such error has occurred,
188 returns a null pointer.
191 the error indication is reset. Thus in the case of two calls
194 where the second call follows the first immediately, the second call
195 will always return a null pointer.
198 deletes a reference to the shared object referenced by
200 If the reference count drops to 0, the object is removed from the
204 Just before removing a shared object in this way, the dynamic linker
207 function, if such a function is defined by the object.
211 is the C language name of the function.
214 is successful, it returns a value of 0.
215 Otherwise it returns -1, and sets an error condition that can be
219 The object-intrinsic functions
223 are called with no arguments, and are not expected to return values.
225 ELF executables need to be linked
230 for symbols defined in the executable to become visible to
236 return the null pointer in the event of errors.
238 returns 0 on success, or -1 if an error occurred.
239 Whenever an error has been detected, a message detailing it can be
240 retrieved via a call to