*** UNIX MANUAL PAGE BROWSER ***

dlopen(3) Library Functions Manual dlopen(3) NAME dlopen, dlsym, dlclose, dlerror - interface to dynamic library loader SYNOPSIS #include <stdio.h> #include <dlfcn.h> void *dlopen(pathname, mode) char *pathname; int mode; void *dlsym(handle, name) void *handle; char *name; void dlclose(handle) void *handle; char *dlerror(void) DESCRIPTION The dlopen function provides an interface to the dynamic library loader to allow shared libraries to be loaded and called at run time. The dlopen function attempts to load pathname in the address space of the process, resolving symbols as appropriate. Any libraries that pathname depends upon are also loaded. If pathname includes a /, dlopen will attempt to open it as specified. Otherwise, dlopen will attempt to locate pathname using shared library search directories in the order specified below (see loader(5) for more details on shared library search directories): The current directory The program's rpath directories LD_LIBRARY_PATH directories Default shared library directories If mode is RTLD_LAZY, then the run-time loader does symbol resolution only as needed. Typically, this means that the first call to a func- tion in the newly loaded library will cause the resolution of the ad- dress of that function to occur. If mode is RTLD_NOW, then the run- time loader must do all symbol binding during the dlopen call. The dlopen function returns a handle that is used by dlsym or dlclose call. If an error occurs, a NULL pointer is returned. If a NULL pathname is specified, dlopen returns a handle for the main executable, which allows access to dynamic symbols in the running pro- gram. The dlsym function returns the address of the symbol name found in the shared library corresponding to handle. If the symbol is not found, a NULL pointer is returned. The dlclose function deallocates the address space for the library cor- responding to handle. The results are undefined if any user function continues to call a symbol resolved in the address space of a library that has since been deallocated by dlclose. The dlerror function returns a string describing the last error that occurred from a call to dlopen, dlclose, or dlsym. NOTES The dlopen and dlclose routines might dynamically change the resolution of certain symbols referenced by a program or its shared library depen- dencies. The dlopen routine might resolve symbols that were previously unresolved, and dlclose might cause resolved symbols to become unre- solved or to be reresolved to a different symbol definition. Use of the dlsym routine is the preferred mechanism for retrieving sym- bol addresses. This routine reliably returns the current address of a symbol at any point in the program, while the dynamic symbol resolution described previously might not function as expected due to compiler op- timizations. For example, the address of a symbol might be saved in a register prior to a dlopen call. The saved address might then be used after the dlopen call, even if the dlopen call changed the resolution of the symbol. Dynamic symbol resolution functions reliably for programs compiled with the -O0 flag. Also, routines that do not call dlopen or dlclose, ei- ther directly or indirectly, can safely depend on dynamic symbol reso- lution. The maximum number of shared libraries that can be loaded simultane- ously by a single process is approximately 60. This limit can be raised by reconfiguring the kernel's vm-mapentries parameter. This pa- rameter should be set to at least three times the desired maximum num- ber of shared libraries that can be loaded by a process. See the man- ual System Administration for instructions on reconfiguring the vm- mapentries parameter. RELATED INFORMATION ld(1), loader(5). delim off dlopen(3)