1.\" $NetBSD: dlfcn.3,v 1.15 2002/02/13 08:17:29 ross 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 \*[Lt]dlfcn.h\*[Gt] 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. 84If the first argument is 85.Dv NULL , 86.Fn dlopen 87returns a handle on the global symbol object. This object 88provides access to all symbols from an ordered set of objects consisting 89of the original program image and any dependencies loaded during startup. 90.Pp 91The second argument has currently no effect, but should be set to 92.Dv DL_LAZY 93for future compatibility. 94.Fn dlopen 95returns a handle to be used in calls to 96.Fn dlclose , 97.Fn dlsym 98and 99.Fn dlctl . 100If the named shared object has already 101been loaded by a previous call to 102.Fn dlopen 103.Pq and not yet unloaded by Fn dlclose , 104a handle referring to the resident copy is returned. 105.Pp 106.Fn dlclose 107unlinks and removes the object referred to by 108.Fa handle 109from the process address space. 110If multiple calls to 111.Fn dlopen 112have been done on this object 113.Po or the object was one loaded at startup time 114.Pc 115the object is removed when its reference count drops to zero. 116.Pp 117.Fn dlsym 118looks for a definition of 119.Fa symbol 120in the shared object designated by 121.Fa handle . 122The symbols address is returned. 123If the symbol cannot be resolved, 124.Dv NULL 125is returned. 126.Pp 127.Fn dladdr 128examines all currently mapped shared objects for a symbol whose address -- 129as mapped in the process address space -- is closest to but not exceeding 130the value passed in the first argument 131.Fa addr . 132The symbols of a shared object are only eligible if 133.Va addr 134is between the base address of the shared object and the value of the 135symbol 136.Dq _end 137in the same shared object. If no object for which this condition holds 138true can be found, 139.Fn dladdr 140will return 0. Otherwise, a non-zero value is returned and the 141.Fa dli 142argument will be used to provide information on the selected symbol 143and the shared object it is contained in. 144The 145.Fa dli 146argument points at a caller-provided 147.Va Dl_info 148structure defined as follows: 149.Bd -literal -offset indent 150typedef struct { 151 const char *dli_fname; /* File defining the symbol */ 152 void *dli_fbase; /* Base address */ 153 const char *dli_sname; /* Symbol name */ 154 void *dli_saddr; /* Symbol address */ 155} Dl_info; 156.Ed 157.Pp 158The member 159.Va dli_sname 160points at the nul-terminated name of the selected symbol, and 161.Va dli_saddr 162is the actual address 163.Pq as it appears in the process address space 164of the symbol. 165The member 166.Va dli_fname 167points at the file name corresponding to the shared object in which the 168symbol was found, while 169.Va dli_fbase 170is the base address at which this shared object is loaded in the process 171address space. 172.Va dli_fname 173and 174.Va dli_fbase 175may be zero if the symbol was found in the internally generated 176.Dq copy 177section 178.Po 179see 180.Xr link 5 181.Pc 182which is not associated with a file. 183Note: both strings pointed at by 184.Va dli_fname 185and 186.Va dli_sname 187reside in memory private to the run-time linker module and should not 188be modified by the caller. 189.Pp 190.Fn dlctl 191provides an interface similar to 192.Xr ioctl 2 193to control several aspects of the run-time linker's operation. 194This interface 195is 196.Ud . 197.Pp 198.Fn dlerror 199return a character string representing the most recent error that has 200occurred while processing one of the other functions described here. 201If no dynamic linking errors have occurred since the last invocation of 202.Fn dlerror , 203.Fn dlerror 204returns 205.Dv NULL . 206Thus, invoking 207.Fn dlerror 208a second time, immediately following a prior invocation, will result in 209.Dv NULL 210being returned. 211.Sh SEE ALSO 212.Xr ld 1 , 213.Xr rtld 1 , 214.Xr link 5 215.Sh HISTORY 216Some of the 217.Nm dl* 218functions first appeared in SunOS 4. 219.Sh BUGS 220An error that occurs while processing a 221.Fn dlopen 222request results in the termination of the program. 223