1.\" $OpenBSD: dlfcn.3,v 1.23 2010/02/20 21:08:11 schwarze Exp $ 2.\" $NetBSD: dlfcn.3,v 1.3 1996/01/09 19:43:34 pk Exp $ 3.\" 4.\" Copyright (c) 1995 Paul Kranenburg 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by Paul Kranenburg. 18.\" 3. The name of the author may not be used to endorse or promote products 19.\" derived from this software without specific prior written permission 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 22.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 23.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 24.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 26.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31.\" 32.Dd $Mdocdate: February 20 2010 $ 33.Dt DLFCN 3 34.Os 35.Sh NAME 36.Nm dlopen , 37.Nm dlclose , 38.Nm dlsym , 39.Nm dladdr , 40.Nm dlctl , 41.Nm dlerror 42.Nd dynamic link interface 43.Sh SYNOPSIS 44.Fd #include <dlfcn.h> 45.Ft "void *" 46.Fn dlopen "const char *path" "int mode" 47.Ft "int" 48.Fn dlclose "void *handle" 49.Ft "void *" 50.Fn dlsym "void *handle" "const char *symbol" 51.Ft "int" 52.Fn dladdr "const void *addr" "Dl_info *info" 53.Ft "int" 54.Fn dlctl "void *handle" "int cmd" "void *data" 55.Ft "const char *" 56.Fn dlerror "void" 57.Sh DESCRIPTION 58These functions provide an interface to the run-time linker 59.Xr ld.so 1 . 60They allow new shared objects to be loaded into a process's address space 61under program control. 62.Pp 63The 64.Fn dlopen 65function takes the name of a shared object as its first argument. 66The shared object is mapped into the address space, relocated, and its external 67references are resolved in the same way as is done with the implicitly loaded 68shared libraries at program startup. 69.Pp 70The 71.Fa path 72parameter can be specified as either an absolute pathname to a shared library 73or just the name of the shared library itself. 74When an absolute pathname is specified, 75only the path provided will be searched for the shared library. 76When just a shared library is specified, 77the same paths will be searched that are used for 78.Dq intrinsic 79shared library searches. 80.Pp 81Shared libraries take the following form: 82.Pp 83.Dl lib\*(Ltname\*(Gt.so[.xx[.yy]] 84.Pp 85When a shared library is specified without a version or with a partial version, 86the same library search rules apply that are used for 87.Dq intrinsic 88shared library searches. 89A null pointer supplied for 90.Fa path 91will return a special 92.Fa handle 93that behaves the same as the 94.Dv RTLD_DEFAULT 95special 96.Fa handle . 97.Pp 98The 99.Fa mode 100parameter specifies symbol resolution time and symbol visibility. 101One of the following values may be used to specify symbol resolution time: 102.Bl -tag -width "RTLD_LAZYXX" -offset indent 103.It Sy RTLD_NOW 104Symbols are resolved immediately. 105.It Sy RTLD_LAZY 106Symbols are resolved when they are first referred to. 107This is the default value if resolution time is unspecified. 108.El 109.Pp 110One of the following values may be used to specify symbol visibility: 111.Pp 112.Bl -tag -width "RTLD_GLOBAL" -compact -offset indent 113.It Sy RTLD_GLOBAL 114The object's symbols and the symbols of its dependencies will be visible to 115other objects. 116.It Sy RTLD_LOCAL 117The object's symbols and the symbols of its dependencies will not be visible to 118other objects. 119This is the default value if visibility is unspecified. 120.El 121.Pp 122To specify both resolution time and visibility, bitwise inclusive OR one of 123each of the above values together. 124If an object was opened with RTLD_LOCAL and later opened with RTLD_GLOBAL, 125then it is promoted to RTLD_GLOBAL. 126.Pp 127.Fn dlopen 128returns a 129.Fa handle 130to be used in calls to 131.Fn dlclose , 132.Fn dlsym , 133and 134.Fn dlctl . 135If the named shared object has already been loaded by a previous call to 136.Fn dlopen 137and not yet unloaded by 138.Fn dlclose , 139a 140.Fa handle 141referring to the resident copy is returned. 142.Pp 143.Fn dlclose 144unlinks and removes the object referred to by 145.Fa handle 146from the process address space. 147If multiple calls to 148.Fn dlopen 149have been done on this object or the object is a dependency of another object 150then the object is removed when its reference count drops to zero. 151.Fn dlclose 152returns 0 on success and non-zero on failure. 153.Pp 154.Fn dlsym 155searches for a definition of 156.Fa symbol 157in the object designated by 158.Fa handle 159and all shared objects that it depends on. 160The symbol's address is returned. 161If the symbol cannot be resolved, 162.Dv NULL 163is returned. 164.Pp 165.Fn dlsym 166may also be called with special 167.Fa handles . 168.Fn dlsym 169respects symbol visibility as specified by the 170.Fn dlopen 171.Fa mode 172parameter. 173However, the symbols of an object's dependencies are always visible to it. 174All shared objects loaded at program startup are globally visible. 175Only the symbols in the main executable that are referenced by a 176shared object at link time will be visible unless it has been linked 177with the --export-dynamic option where all of its symbols will be 178visible. 179The following special 180.Fa handles 181may be used with 182.Fn dlsym : 183.Bl -tag -width "RTLD_DEFAULTXX" -offset indent 184.It Sy NULL 185Interpreted as a reference to the executable or shared object 186from which the call is being made. 187Thus an object can reference its own symbols and the symbols of its 188dependencies without calling 189.Fn dlopen . 190.It Sy RTLD_DEFAULT 191All the visible shared objects and the executable will be searched in the order they 192were loaded. 193.It Sy RTLD_NEXT 194The search for 195.Fa symbol 196is limited to the visible shared objects which were loaded after the one issuing the 197call to 198.Fn dlsym . 199Thus, if 200.Fn dlsym 201is called from the main program, all the visible shared libraries are searched. 202If it is called from a shared library, all subsequently visible shared 203libraries are searched. 204.It Sy RTLD_SELF 205The search for 206.Fa symbol 207is limited to the shared object issuing the call to 208.Fn dlsym 209and those shared objects which were loaded after it that are visible. 210.El 211.Pp 212.Fn dladdr 213queries the dynamic linker for information about the shared object 214containing the address 215.Fa addr . 216The information is returned in the structure specified by 217.Fa info . 218The structure contains at least the following members: 219.Bl -tag -width "XXXconst char *dli_fname" 220.It Li "const char *dli_fname" 221The pathname of the shared object containing the address 222.Fa addr . 223.It Li "void *dli_fbase" 224The base address at which the shared object is mapped into the 225address space of the calling process. 226.It Li "const char *dli_sname" 227The name of the nearest run-time symbol with a address less than or 228equal to 229.Fa addr . 230.Pp 231If no symbol with a suitable address is found, both this field and 232.Va dli_saddr 233are set to 234.Dv NULL . 235.It Li "void *dli_saddr" 236The address of the symbol returned in 237.Va dli_sname . 238.El 239.Pp 240If a mapped shared object containing 241.Fa addr 242cannot be found, 243.Fn dladdr 244returns 0. 245In that case, a message detailing the failure can be retrieved by 246calling 247.Fn dlerror . 248On success, a non-zero value is returned. 249Note: both strings pointed at by 250.Va dli_fname 251and 252.Va dli_sname 253reside in memory private to the run-time linker module and should not 254be modified by the caller. 255.Pp 256In dynamically linked programs, the address of a global function will 257point to its program linkage table entry, rather than to the entry 258point of the function itself. 259This causes most global functions to appear to be defined within the 260main executable, rather than in the shared libraries where the actual 261code resides. 262.Pp 263.Fn dlctl 264provides an interface similar to 265.Xr ioctl 2 266to control several aspects of the run-time linker's operation. 267This interface is currently under development. 268.Pp 269.Fn dlerror 270returns a character string representing the most recent error that has 271occurred while processing one of the other functions described here. 272If no dynamic linking errors have occurred since the last invocation of 273.Fn dlerror , 274.Fn dlerror 275returns 276.Dv NULL . 277Thus, invoking 278.Fn dlerror 279a second time, immediately following a prior invocation, will result in 280.Dv NULL 281being returned. 282.Sh SEE ALSO 283.Xr ld 1 , 284.Xr ld.so 1 , 285.Xr link 5 286.Sh HISTORY 287Some of the 288.Nm dl* 289functions first appeared in SunOS 4. 290