1.\" $NetBSD: dlfcn.3,v 1.23 2009/03/13 14:23:30 joerg 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd March 31, 2008 31.Dt DLFCN 3 32.Os 33.Sh NAME 34.Nm dlopen , 35.Nm dlclose , 36.Nm dlsym , 37.Nm dladdr , 38.Nm dlctl , 39.Nm dlerror 40.Nd dynamic link interface 41.Sh LIBRARY 42(These functions are not in a library. They are included in every 43dynamically linked program automatically.) 44.Sh SYNOPSIS 45.In dlfcn.h 46.Ft "void *" 47.Fn dlopen "const char *path" "int mode" 48.Ft "int" 49.Fn dlclose "void *handle" 50.Ft "void *" 51.Fn dlsym "void * restrict handle" "const char * restrict symbol" 52.Ft "int" 53.Fn dladdr "void * restrict addr" "Dl_info * restrict dli" 54.Ft "int" 55.Fn dlctl "void *handle" "int cmd" "void *data" 56.Ft "char *" 57.Fn dlerror "void" 58.Sh DESCRIPTION 59These functions provide an interface to the run-time linker 60.Xr ld.so 1 . 61They allow new shared objects to be loaded into the process' address space 62under program control. 63The 64.Fn dlopen 65function takes a name of a shared object as the first argument. 66The shared object is mapped into the address space, relocated and 67its external references are resolved in the same way as is done 68with the implicitly loaded shared libraries at program startup. 69The argument can either be an absolute pathname or it can be of the form 70.Sm off 71.Do lib Ao name Ac .so Oo .xx Oo .yy Oc Oc 72.Dc 73.Sm on 74in which case the same library search rules apply that are used for 75.Dq intrinsic 76shared library searches. 77If the first argument is 78.Dv NULL , 79.Fn dlopen 80returns a handle on the global symbol object. This object 81provides access to all symbols from an ordered set of objects consisting 82of the original program image and any dependencies loaded during startup. 83.Pp 84The second argument has currently no effect, but should be set to 85.Dv RTLD_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 referring 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 process 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 const 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 is 188.Ud 189.Pp 190.Fn dlerror 191returns a character string representing the most recent error that has 192occurred while processing one of the other functions described here. 193If no dynamic linking errors have occurred since the last invocation of 194.Fn dlerror , 195.Fn dlerror 196returns 197.Dv NULL . 198Thus, invoking 199.Fn dlerror 200a second time, immediately following a prior invocation, will result in 201.Dv NULL 202being returned. 203.Sh SEE ALSO 204.Xr ld 1 , 205.Xr rtld 1 , 206.Xr link 5 207.Sh HISTORY 208Some of the 209.Nm dl* 210functions first appeared in SunOS 4. 211.Sh BUGS 212An error that occurs while processing a 213.Fn dlopen 214request results in the termination of the program. 215