1.\" $NetBSD: dlfcn.3,v 1.39 2020/01/13 16:01:37 uwe 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 January 13, 2020 31.Dt DLFCN 3 32.Os 33.Sh NAME 34.Nm dlopen , 35.Nm dlclose , 36.Nm dlsym , 37.Nm dlvsym , 38.Nm dladdr , 39.Nm dlctl , 40.Nm dlerror 41.Nd dynamic link interface 42.Sh LIBRARY 43(These functions are not in a library. 44They are included in every 45dynamically linked program automatically.) 46.Sh SYNOPSIS 47.In dlfcn.h 48.Ft "void *" 49.Fn dlopen "const char *path" "int mode" 50.Ft "int" 51.Fn dlclose "void *handle" 52.Ft "void *" 53.Fn dlsym "void * restrict handle" "const char * restrict symbol" 54.Ft "void *" 55.Fn dlvsym "void * restrict handle" "const char * restrict symbol" "const char *version" 56.Ft "int" 57.Fn dladdr "void * restrict addr" "Dl_info * restrict dli" 58.Ft "int" 59.Fn dlctl "void *handle" "int cmd" "void *data" 60.Ft "char *" 61.Fn dlerror "void" 62.Sh DESCRIPTION 63These functions provide an interface to the run-time linker 64.Xr ld.so 1 . 65They allow new shared objects to be loaded into the process' address space 66under program control. 67.Pp 68The 69.Fn dlopen 70function takes the name of a shared object as the first argument. 71The 72.Fa path 73argument can be specified as either an absolute pathname to a shared object 74or just the name of the shared object itself. 75When an absolute pathname is specified, 76only the path provided will be searched. 77When just a shared object name is specified, the same search rules apply that 78are used for 79.Dq intrinsic 80shared object searches. 81.Po 82see 83.Xr ld.elf_so 1 84.Pc 85.Pp 86Shared libraries take the following form: 87.Do lib Ns Ao name Ac Ns .so Ns Oo .xx Ns Oo .yy Oc Oc Dc . 88.Pp 89The shared object is mapped into the address space, relocated, and 90its external references are resolved in the same way as is done 91with the implicitly loaded shared libraries at program startup. 92.Pp 93If the first argument is 94.Dv NULL , 95.Fn dlopen 96returns a 97.Fa handle 98on the global symbol object. 99This object 100provides access to all symbols from an ordered set of objects consisting 101of the original program image and any dependencies loaded during startup. 102.Pp 103The 104.Fa mode 105parameter specifies symbol resolution time and symbol visibility. 106One of the following values may be used to specify symbol resolution time: 107.Bl -tag -width ".Dv RTLD_NODELETE" -offset indent 108.It Dv RTLD_NOW 109Symbols are resolved immediately. 110.It Dv RTLD_LAZY 111Symbols are resolved when they are first referred to. 112This is the default value if resolution time is unspecified. 113.El 114.Pp 115One of the following values may be used to specify symbol visibility: 116.Bl -tag -width ".Dv RTLD_NODELETE" -offset indent 117.It Dv RTLD_GLOBAL 118The object's symbols and the symbols of its dependencies will be visible to 119other objects. 120.It Dv RTLD_LOCAL 121The object's symbols and the symbols of its dependencies will not be visible to 122other objects. 123This is the default value if visibility is unspecified. 124.El 125.Pp 126To specify both resolution time and visibility, bitwise inclusive OR one of 127each of the above values together. 128If an object was opened with 129.Dv RTLD_LOCAL 130and later opened with 131.Dv RTLD_GLOBAL , 132then it is promoted to 133.Dv RTLD_GLOBAL . 134.Pp 135Additionally, one of the following flags may be ORed into the 136.Fa mode 137argument: 138.Bl -tag -width ".Dv RTLD_NODELETE" -offset indent 139.It Dv RTLD_NODELETE 140Prevents unload of the loaded object on 141.Fn dlclose . 142The same behaviour may be requested by 143.Fl z Cm nodelete 144option of the static linker 145.Xr ld 1 . 146.It Dv RTLD_NOLOAD 147Only return valid handle for the object if it is already loaded in 148the process address space, otherwise do not load the object and return 149.Dv NULL . 150.El 151.Pp 152.Fn dlopen 153returns a 154.Fa handle 155to be used in calls to 156.Fn dlclose , 157.Fn dlsym , 158.Fn dlvsym , 159and 160.Fn dlctl . 161If the named shared object has already 162been loaded by a previous call to 163.Fn dlopen 164.Pq and not yet unloaded by Fn dlclose , 165a 166.Fa handle 167referring to the resident copy is returned. 168.Pp 169.Fn dlclose 170unlinks and removes the object referred to by 171.Fa handle 172from the process address space. 173If multiple calls to 174.Fn dlopen 175have been done on this object, or the object was one loaded at startup time, 176or the object is a dependency of another object 177then the object is removed when its reference count drops to zero. 178.Fn dlclose 179returns 0 on success and non-zero on failure. 180.Pp 181.Fn dlsym 182looks for a definition of 183.Fa symbol 184in the shared object designated by 185.Fa handle , 186and all shared objects that are listed as dependencies. 187The symbol's address is returned. 188If the symbol cannot be resolved, 189.Dv NULL 190is returned. 191.Pp 192.Fn dlsym 193may also be called with special 194.Fa handle 195values. 196.Fn dlsym 197respects symbol visibility as specified by the 198.Fn dlopen 199.Fa mode 200parameter. 201However, the symbols of an object's dependencies are always visible to it. 202All shared objects loaded at program startup are globally visible. 203Only the symbols in the main executable that are referenced by a 204shared object at link time will be visible unless it has been linked 205with the 206.Fl Fl export-dynamic 207option where all of its symbols will be visible. 208The following special 209.Fa handle 210values may be used with 211.Fn dlsym : 212.Bl -tag -width ".Dv RTLD_DEFAULT" -offset indent 213.It Dv NULL 214Interpreted as a reference to the executable or shared object 215from which the call is being made. 216Thus an object can reference its own symbols and the symbols of its 217dependencies without calling 218.Fn dlopen . 219.It Dv RTLD_DEFAULT 220All the visible shared objects and the executable will be searched in the order 221they were loaded. 222.It Dv RTLD_NEXT 223The search for 224.Fa symbol 225is limited to the visible shared objects which were loaded after the one 226issuing the call to 227.Fn dlsym . 228Thus, if 229.Fn dlsym 230is called from the main program, all the visible shared libraries are searched. 231If it is called from a shared library, all subsequently visible shared 232libraries are searched. 233.It Dv RTLD_SELF 234The search for 235.Fa symbol 236is limited to the shared object issuing the call to 237.Fn dlsym 238and those shared objects which were loaded after it that are visible. 239.El 240.Pp 241.Fn dlvsym 242does the same as 243.Fn dlsym 244but takes a 245.Fa version 246string as an additional argument. 247Both the 248.Fa symbol 249and the 250.Fa version 251must match in order for the symbol to be resolved. 252.Pp 253.Fn dladdr 254examines all currently mapped shared objects for a symbol whose address \(em 255as mapped in the process address space \(em is closest to but not exceeding 256the value passed in the first argument 257.Fa addr . 258The symbols of a shared object are only eligible if 259.Fa addr 260is between the base address of the shared object and the value of the 261symbol 262.Va _end 263in the same shared object. 264If no object for which this condition holds 265true can be found, 266.Fn dladdr 267will return 0. 268Otherwise, a non-zero value is returned and the 269.Fa dli 270argument will be used to provide information on the selected symbol 271and the shared object it is contained in. 272The 273.Fa dli 274argument points at a caller-provided 275.Vt Dl_info 276structure defined as follows: 277.Bd -literal -offset indent 278typedef struct { 279 const char *dli_fname; /* File defining the symbol */ 280 void *dli_fbase; /* Base address */ 281 const char *dli_sname; /* Symbol name */ 282 const void *dli_saddr; /* Symbol address */ 283} Dl_info; 284.Ed 285.Pp 286The structure members are further described as follows: 287.Bl -tag -width "Va" 288.It Va dli_fname 289The pathname of the shared object containing the address 290.Fa addr . 291.It Va dli_fbase 292The base address at which this shared object is loaded in the process 293address space. 294This may be zero if the symbol was found in the internally generated 295.Dq copy 296section 297.Po 298see 299.Xr link 5 300.Pc 301which is not associated with a file. 302.It Va dli_sname 303points at the nul-terminated name of the selected symbol 304.It Va dli_saddr 305is the actual address 306.Pq as it appears in the process address space 307of the symbol. 308.El 309.Pp 310Note: both strings pointed at by 311.Va dli_fname 312and 313.Va dli_sname 314reside in memory private to the run-time linker module and should not 315be modified by the caller. 316.Pp 317In dynamically linked programs, the address of a global function will 318point to its program linkage table entry, rather than to the entry 319point of the function itself. 320This causes most global functions to appear to be defined within the 321main executable, rather than in the shared libraries where the actual 322code resides. 323.Pp 324.Fn dlctl 325provides an interface similar to 326.Xr ioctl 2 327to control several aspects of the run-time linker's operation. 328This interface is 329.Ud 330.Pp 331.Fn dlerror 332returns a character string representing the most recent error that has 333occurred while processing one of the other functions described here. 334If no dynamic linking errors have occurred since the last invocation of 335.Fn dlerror , 336.Fn dlerror 337returns 338.Dv NULL . 339Thus, invoking 340.Fn dlerror 341a second time, immediately following a prior invocation, will result in 342.Dv NULL 343being returned. 344.Sh ERRORS 345The error 346.Dq Cannot dlopen non-loadable /usr/lib/libpthread.so.1 347is generated when a program 348.Fn dlopen Ns No s 349a module that needs libpthread but isn't linked against it itself. 350.Sh SEE ALSO 351.Xr ld 1 , 352.Xr rtld 1 , 353.Xr dlinfo 3 , 354.Xr link 5 355.Sh HISTORY 356Some of the 357.Nm dl* 358functions first appeared in SunOS 4. 359