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