1.\" $OpenBSD: dlfcn.3,v 1.31 2021/06/02 07:29:03 semarie 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: June 2 2021 $ 33.Dt DLOPEN 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.In 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 "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<name>.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 127Additionally, the following flag may be ORed into the mode argument: 128.Pp 129.Bl -tag -width "RTLD_NODELETE" -compact -offset indent 130.It Sy RTLD_NODELETE 131Prevents unload of the loaded object on 132.Fn dlclose . 133.El 134.Pp 135The main executable's symbols are normally invisible to 136.Fn dlopen 137symbol resolution. 138Those symbols will be visible if linking is done with 139.Xr gcc 1 140.Fl rdynamic , 141which is equivalent to 142.Xr ld 1 143.Fl -export-dynamic . 144.Pp 145All shared objects loaded at program startup are globally visible. 146.Pp 147.Fn dlopen 148returns a 149.Fa handle 150to be used in calls to 151.Fn dlclose , 152.Fn dlsym , 153and 154.Fn dlctl . 155If the named shared object has already been loaded by a previous call to 156.Fn dlopen 157and not yet unloaded by 158.Fn dlclose , 159a 160.Fa handle 161referring to the resident copy is returned. 162.Pp 163.Fn dlclose 164unlinks and removes the object referred to by 165.Fa handle 166from the process address space. 167If multiple calls to 168.Fn dlopen 169have been done on this object or the object is a dependency of another object 170then the object is removed when its reference count drops to zero. 171.Fn dlclose 172returns 0 on success and non-zero on failure. 173.Pp 174.Fn dlsym 175searches for a definition of 176.Fa symbol 177in the object designated by 178.Fa handle 179and all shared objects that it depends on. 180The symbol's address is returned. 181If the symbol cannot be resolved, 182.Dv NULL 183is returned. 184.Pp 185.Fn dlsym 186may also be called with special 187.Fa handles . 188.Fn dlsym 189respects symbol visibility as specified by the 190.Fn dlopen 191.Fa mode 192parameter. 193However, the symbols of an object's dependencies are always visible to it. 194The following special 195.Fa handles 196may be used with 197.Fn dlsym : 198.Bl -tag -width "RTLD_DEFAULTXX" -offset indent 199.It Sy NULL 200Interpreted as a reference to the executable or shared object 201from which the call is being made. 202Thus an object can reference its own symbols and the symbols of its 203dependencies without calling 204.Fn dlopen . 205.It Sy RTLD_DEFAULT 206All the visible shared objects and the executable will be searched in the order they 207were loaded. 208.It Sy RTLD_NEXT 209The search for 210.Fa symbol 211is limited to the visible shared objects which were loaded after the one issuing the 212call to 213.Fn dlsym . 214Thus, if 215.Fn dlsym 216is called from the main program, all the visible shared libraries are searched. 217If it is called from a shared library, all subsequently visible shared 218libraries are searched. 219.It Sy RTLD_SELF 220The search for 221.Fa symbol 222is limited to the shared object issuing the call to 223.Fn dlsym 224and those shared objects which were loaded after it that are visible. 225.El 226.Pp 227.Fn dladdr 228queries the dynamic linker for information about the shared object 229containing the address 230.Fa addr . 231The information is returned in the structure specified by 232.Fa info . 233The structure contains at least the following members: 234.Bl -tag -width "XXXconst char *dli_fname" 235.It Li "const char *dli_fname" 236The pathname of the shared object containing the address 237.Fa addr . 238.It Li "void *dli_fbase" 239The base address at which the shared object is mapped into the 240address space of the calling process. 241.It Li "const char *dli_sname" 242The name of the nearest run-time symbol with an address less than or 243equal to 244.Fa addr . 245.Pp 246If no symbol with a suitable address is found, both this field and 247.Va dli_saddr 248are set to 249.Dv NULL . 250.It Li "void *dli_saddr" 251The address of the symbol returned in 252.Va dli_sname . 253.El 254.Pp 255If a mapped shared object containing 256.Fa addr 257cannot be found, 258.Fn dladdr 259returns 0. 260In that case, a message detailing the failure can be retrieved by 261calling 262.Fn dlerror . 263On success, a non-zero value is returned. 264Note: both strings pointed at by 265.Va dli_fname 266and 267.Va dli_sname 268reside in memory private to the run-time linker module and should not 269be modified by the caller. 270.Pp 271In dynamically linked programs, the address of a global function will 272point to its program linkage table entry, rather than to the entry 273point of the function itself. 274This causes most global functions to appear to be defined within the 275main executable, rather than in the shared libraries where the actual 276code resides. 277.Pp 278.Fn dlctl 279provides an interface similar to 280.Xr ioctl 2 281to control several aspects of the run-time linker's operation. 282This interface is currently under development. 283.Pp 284.Fn dlerror 285returns a character string representing the most recent error that has 286occurred while processing one of the other functions described here. 287If no dynamic linking errors have occurred since the last invocation of 288.Fn dlerror , 289.Fn dlerror 290returns 291.Dv NULL . 292Thus, invoking 293.Fn dlerror 294a second time, immediately following a prior invocation, will result in 295.Dv NULL 296being returned. 297.Sh SEE ALSO 298.Xr ld 1 , 299.Xr ld.so 1 , 300.Xr elf 5 301.Sh HISTORY 302Some of the 303.Nm dl* 304functions first appeared in SunOS 4. 305