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