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