.\" $NetBSD: dlfcn.3,v 1.11 2000/06/17 19:09:21 christos Exp $ .\" .\" Copyright (c) 1998 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Paul Kranenburg. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the NetBSD .\" Foundation, Inc. and its contributors. .\" 4. Neither the name of The NetBSD Foundation nor the names of its .\" contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd September 30, 1995 .Dt DLFCN 3 .Os .Sh NAME .Nm dlopen , .Nm dlclose , .Nm dlsym , .Nm dlctl , .Nm dlerror .Nd dynamic link interface .Sh LIBRARY (These functions are not in a library. They are included in every dynamically linked program automatically.) .Sh SYNOPSIS .Fd #include .Ft "void *" .Fn dlopen "const char *path" "int mode" .Ft "int" .Fn dlclose "void *handle" .Ft "void *" .Fn dlsym "void *handle" "const char *symbol" .Ft "int" .Fn dladdr "void *addr" "Dl_info *dli" .Ft "int" .Fn dlctl "void *handle" "int cmd" "void *data" .Ft "char *" .Fn dlerror "void" .Sh DESCRIPTION These functions provide an interface to the run-time linker .Xr ld.so 1 . They allow new shared objects to be loaded into the process' address space under program control. The .Fn dlopen function takes a name of a shared object as the first argument. The shared object is mapped into the address space, relocated and its external references are resolved in the same way as is done with the implicitly loaded shared libraries at program startup. The argument can either be an absolute pathname or it can be of the form .Sm off .Do Xo lib Ao name Ac .so .Op .xx Op .yy Xc .Dc .Sm on in which case the same library search rules apply that are used for .Dq intrinsic shared library searches. If the first argument is .Dv NULL , .Fn dlopen returns a handle on the global symbol object. This object provides access to all symbols from an ordered set of objects consisting of the original program image and any dependencies loaded during startup. .Pp The second argument has currently no effect, but should be set to .Dv DL_LAZY for future compatibility. .Fn dlopen returns a handle to be used in calls to .Fn dlclose , .Fn dlsym and .Fn dlctl . If the named shared object has already been loaded by a previous call to .Fn dlopen .Pq and not yet unloaded by Fn dlclose , a handle refering to the resident copy is returned. .Pp .Fn dlclose unlinks and removes the object referred to by .Fa handle from the process address space. If multiple calls to .fn dlopen have been done on this object .Po or the object was one loaded at startup time .Pc the object is removed when its reference count drops to zero. .Pp .Fn dlsym looks for a definition of .Fa symbol in the shared object designated by .Fa handle . The symbols address is returned. If the symbol cannot be resolved, .Dv NULL is returned. .Pp .Fn dladdr examines all currently mapped shared objects for a symbol whose address -- as mapped in the proces address space -- is closest to but not exceeding the value passed in the first argument .Fa addr . The symbols of a shared object are only eligible if .Va addr is between the base address of the shared object and the value of the symbol .Dq _end in the same shared object. If no object for which this condition holds true can be found, .Fn dladdr will return 0. Otherwise, a non-zero value is returned and the .Fa dli argument will be used to provide information on the selected symbol and the shared object it is contained in. The .Fa dli argument points at a caller-provided .Va Dl_info structure defined as follows: .Bd -literal -offset indent typedef struct { const char *dli_fname; /* File defining the symbol */ void *dli_fbase; /* Base address */ const char *dli_sname; /* Symbol name */ void *dli_saddr; /* Symbol address */ } Dl_info; .Ed .Pp The member .Va dli_sname points at the nul-terminated name of the selected symbol, and .Va dli_saddr is the actual address .Pq as it appears in the process address space of the symbol. The member .Va dli_fname points at the file name corresponding to the shared object in which the symbol was found, while .Va dli_fbase is the base address at which this shared object is loaded in the process address space. .Va dli_fname and .Va dli_fbase may be zero if the symbol was found in the internally generated .Dq copy section .Po see .Xr link 5 .Pc which is not associated with a file. Note: both strings pointed at by .Va dli_fname and .Va dli_sname reside in memory private to the run-time linker module and should not be modified by the caller. .Pp .Fn dlctl provides an interface similar to .Xr ioctl 2 to control several aspects of the run-time linker's operation. This interface is .Ud . .Pp .Fn dlerror return a character string representing the most recent error that has occurred while processing one of the other functions described here. If no dynamic linking errors have occured since the last invocation of .Fn dlerror , .Fn dlerror returns .Dv NULL . Thus, invoking .Fn dlerror a second time, immediately following a prior invocation, will result in .Dv NULL being returned. .Sh SEE ALSO .Xr ld 1 , .Xr rtld 1 , .Xr link 5 .Sh HISTORY Some of the .Nm dl* functions first appeared in SunOS 4. .Sh BUGS An error that occurs while processing a .Fn dlopen request results in the termination of the program.