1.\" $NetBSD: dlfcn.3,v 1.18 2004/11/11 14:47:02 jmmv 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 dladdr , 45.Nm dlctl , 46.Nm dlerror 47.Nd dynamic link interface 48.Sh LIBRARY 49(These functions are not in a library. They are included in every 50dynamically linked program automatically.) 51.Sh SYNOPSIS 52.In dlfcn.h 53.Ft "void *" 54.Fn dlopen "const char *path" "int mode" 55.Ft "int" 56.Fn dlclose "void *handle" 57.Ft "void *" 58.Fn dlsym "void *handle" "const char *symbol" 59.Ft "int" 60.Fn dladdr "void *addr" "Dl_info *dli" 61.Ft "int" 62.Fn dlctl "void *handle" "int cmd" "void *data" 63.Ft "char *" 64.Fn dlerror "void" 65.Sh DESCRIPTION 66These functions provide an interface to the run-time linker 67.Xr ld.so 1 . 68They allow new shared objects to be loaded into the process' address space 69under program control. 70The 71.Fn dlopen 72function takes a name of a shared object as the first argument. 73The shared object is mapped into the address space, relocated and 74its external references are resolved in the same way as is done 75with the implicitly loaded shared libraries at program startup. 76The argument can either be an absolute pathname or it can be of the form 77.Sm off 78.Do Xo lib Ao name Ac .so 79.Op .xx Op .yy Xc 80.Dc 81.Sm on 82in which case the same library search rules apply that are used for 83.Dq intrinsic 84shared library searches. 85If the first argument is 86.Dv NULL , 87.Fn dlopen 88returns a handle on the global symbol object. This object 89provides access to all symbols from an ordered set of objects consisting 90of the original program image and any dependencies loaded during startup. 91.Pp 92The second argument has currently no effect, but should be set to 93.Dv DL_LAZY 94for future compatibility. 95.Fn dlopen 96returns a handle to be used in calls to 97.Fn dlclose , 98.Fn dlsym 99and 100.Fn dlctl . 101If the named shared object has already 102been loaded by a previous call to 103.Fn dlopen 104.Pq and not yet unloaded by Fn dlclose , 105a handle referring to the resident copy is returned. 106.Pp 107.Fn dlclose 108unlinks and removes the object referred to by 109.Fa handle 110from the process address space. 111If multiple calls to 112.Fn dlopen 113have been done on this object 114.Po or the object was one loaded at startup time 115.Pc 116the object is removed when its reference count drops to zero. 117.Pp 118.Fn dlsym 119looks for a definition of 120.Fa symbol 121in the shared object designated by 122.Fa handle . 123The symbols address is returned. 124If the symbol cannot be resolved, 125.Dv NULL 126is returned. 127.Pp 128.Fn dladdr 129examines all currently mapped shared objects for a symbol whose address -- 130as mapped in the process address space -- is closest to but not exceeding 131the value passed in the first argument 132.Fa addr . 133The symbols of a shared object are only eligible if 134.Va addr 135is between the base address of the shared object and the value of the 136symbol 137.Dq _end 138in the same shared object. If no object for which this condition holds 139true can be found, 140.Fn dladdr 141will return 0. Otherwise, a non-zero value is returned and the 142.Fa dli 143argument will be used to provide information on the selected symbol 144and the shared object it is contained in. 145The 146.Fa dli 147argument points at a caller-provided 148.Va Dl_info 149structure defined as follows: 150.Bd -literal -offset indent 151typedef struct { 152 const char *dli_fname; /* File defining the symbol */ 153 void *dli_fbase; /* Base address */ 154 const char *dli_sname; /* Symbol name */ 155 const void *dli_saddr; /* Symbol address */ 156} Dl_info; 157.Ed 158.Pp 159The member 160.Va dli_sname 161points at the nul-terminated name of the selected symbol, and 162.Va dli_saddr 163is the actual address 164.Pq as it appears in the process address space 165of the symbol. 166The member 167.Va dli_fname 168points at the file name corresponding to the shared object in which the 169symbol was found, while 170.Va dli_fbase 171is the base address at which this shared object is loaded in the process 172address space. 173.Va dli_fname 174and 175.Va dli_fbase 176may be zero if the symbol was found in the internally generated 177.Dq copy 178section 179.Po 180see 181.Xr link 5 182.Pc 183which is not associated with a file. 184Note: both strings pointed at by 185.Va dli_fname 186and 187.Va dli_sname 188reside in memory private to the run-time linker module and should not 189be modified by the caller. 190.Pp 191.Fn dlctl 192provides an interface similar to 193.Xr ioctl 2 194to control several aspects of the run-time linker's operation. 195This interface 196is 197.Ud . 198.Pp 199.Fn dlerror 200returns a character string representing the most recent error that has 201occurred while processing one of the other functions described here. 202If no dynamic linking errors have occurred since the last invocation of 203.Fn dlerror , 204.Fn dlerror 205returns 206.Dv NULL . 207Thus, invoking 208.Fn dlerror 209a second time, immediately following a prior invocation, will result in 210.Dv NULL 211being returned. 212.Sh SEE ALSO 213.Xr ld 1 , 214.Xr rtld 1 , 215.Xr link 5 216.Sh HISTORY 217Some of the 218.Nm dl* 219functions first appeared in SunOS 4. 220.Sh BUGS 221An error that occurs while processing a 222.Fn dlopen 223request results in the termination of the program. 224