1.\" $NetBSD: dlfcn.3,v 1.10 1999/07/20 22:38:49 perry Exp $ 2.\" 3.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd September 30, 1995 38.Dt DLFCN 3 39.Os 40.Sh NAME 41.Nm dlopen , 42.Nm dlclose , 43.Nm dlsym , 44.Nm dlctl , 45.Nm dlerror 46.Nd dynamic link interface 47.Sh LIBRARY 48(These functions are not in a library. They are included in every 49dynamically linked program automatically.) 50.Sh SYNOPSIS 51.Fd #include <dlfcn.h> 52.Ft "void *" 53.Fn dlopen "const char *path" "int mode" 54.Ft "int" 55.Fn dlclose "void *handle" 56.Ft "void *" 57.Fn dlsym "void *handle" "const char *symbol" 58.Ft "int" 59.Fn dladdr "void *addr" "Dl_info *dli" 60.Ft "int" 61.Fn dlctl "void *handle" "int cmd" "void *data" 62.Ft "char *" 63.Fn dlerror "void" 64.Sh DESCRIPTION 65These functions provide an interface to the run-time linker 66.Xr ld.so 1 . 67They allow new shared objects to be loaded into the process' address space 68under program control. 69The 70.Fn dlopen 71function takes a name of a shared object as the first argument. 72The shared object is mapped into the address space, relocated and 73its external references are resolved in the same way as is done 74with the implicitly loaded shared libraries at program startup. 75The argument can either be an absolute pathname or it can be of the form 76.Sm off 77.Do Xo lib Ao name Ac .so 78.Op .xx Op .yy Xc 79.Dc 80.Sm on 81in which case the same library search rules apply that are used for 82.Dq intrinsic 83shared library searches. 84The second argument has currently no effect, but should be set to 85.Dv DL_LAZY 86for future compatibility. 87.Fn dlopen 88returns a handle to be used in calls to 89.Fn dlclose , 90.Fn dlsym 91and 92.Fn dlctl . 93If the named shared object has already 94been loaded by a previous call to 95.Fn dlopen 96.Pq and not yet unloaded by Fn dlclose , 97a handle refering to the resident copy is returned. 98.Pp 99.Fn dlclose 100unlinks and removes the object referred to by 101.Fa handle 102from the process address space. 103If multiple calls to 104.fn dlopen 105have been done on this object 106.Po or the object was one loaded at startup time 107.Pc 108the object is removed when its reference count drops to zero. 109.Pp 110.Fn dlsym 111looks for a definition of 112.Fa symbol 113in the shared object designated by 114.Fa handle . 115The symbols address is returned. 116If the symbol cannot be resolved, 117.Dv NULL 118is returned. 119.Pp 120.Fn dladdr 121examines all currently mapped shared objects for a symbol whose address -- 122as mapped in the proces address space -- is closest to but not exceeding 123the value passed in the first argument 124.Fa addr . 125The symbols of a shared object are only eligible if 126.Va addr 127is between the base address of the shared object and the value of the 128symbol 129.Dq _end 130in the same shared object. If no object for which this condition holds 131true can be found, 132.Fn dladdr 133will return 0. Otherwise, a non-zero value is returned and the 134.Fa dli 135argument will be used to provide information on the selected symbol 136and the shared object it is contained in. 137The 138.Fa dli 139argument points at a caller-provided 140.Va Dl_info 141structure defined as follows: 142.Bd -literal -offset indent 143typedef struct { 144 const char *dli_fname; /* File defining the symbol */ 145 void *dli_fbase; /* Base address */ 146 const char *dli_sname; /* Symbol name */ 147 void *dli_saddr; /* Symbol address */ 148} Dl_info; 149.Ed 150.Pp 151The member 152.Va dli_sname 153points at the nul-terminated name of the selected symbol, and 154.Va dli_saddr 155is the actual address 156.Pq as it appears in the process address space 157of the symbol. 158The member 159.Va dli_fname 160points at the file name corresponding to the shared object in which the 161symbol was found, while 162.Va dli_fbase 163is the base address at which this shared object is loaded in the process 164address space. 165.Va dli_fname 166and 167.Va dli_fbase 168may be zero if the symbol was found in the internally generated 169.Dq copy 170section 171.Po 172see 173.Xr link 5 174.Pc 175which is not associated with a file. 176Note: both strings pointed at by 177.Va dli_fname 178and 179.Va dli_sname 180reside in memory private to the run-time linker module and should not 181be modified by the caller. 182.Pp 183.Fn dlctl 184provides an interface similar to 185.Xr ioctl 2 186to control several aspects of the run-time linker's operation. 187This interface 188is 189.Ud . 190.Pp 191.Fn dlerror 192return a character string representing the most recent error that has 193occurred while processing one of the other functions described here. 194If no dynamic linking errors have occured since the last invocation of 195.Fn dlerror , 196.Fn dlerror 197returns 198.Dv NULL . 199Thus, invoking 200.Fn dlerror 201a second time, immediately following a prior invocation, will result in 202.Dv NULL 203being returned. 204.Sh SEE ALSO 205.Xr ld 1 , 206.Xr rtld 1 , 207.Xr link 5 208.Sh HISTORY 209Some of the 210.Nm dl* 211functions first appeared in SunOS 4. 212.Sh BUGS 213An error that occurs while processing a 214.Fn dlopen 215request results in the termination of the program. 216