1.\" This source code is a product of Sun Microsystems, Inc. and is provided 2.\" for unrestricted use provided that this legend is included on all tape 3.\" media and as a part of the software program in whole or part. Users 4.\" may copy or modify this source code without charge, but are not authorized 5.\" to license or distribute it to anyone else except as part of a product or 6.\" program developed by the user. 7.\" 8.\" THIS PROGRAM CONTAINS SOURCE CODE COPYRIGHTED BY SUN MICROSYSTEMS, INC. 9.\" SUN MICROSYSTEMS, INC., MAKES NO REPRESENTATIONS ABOUT THE SUITABLITY 10.\" OF SUCH SOURCE CODE FOR ANY PURPOSE. IT IS PROVIDED "AS IS" WITHOUT 11.\" EXPRESS OR IMPLIED WARRANTY OF ANY KIND. SUN MICROSYSTEMS, INC. DISCLAIMS 12.\" ALL WARRANTIES WITH REGARD TO SUCH SOURCE CODE, INCLUDING ALL IMPLIED 13.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN 14.\" NO EVENT SHALL SUN MICROSYSTEMS, INC. BE LIABLE FOR ANY SPECIAL, INDIRECT, 15.\" INCIDENTAL, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING 16.\" FROM USE OF SUCH SOURCE CODE, REGARDLESS OF THE THEORY OF LIABILITY. 17.\" 18.\" This source code is provided with no support and without any obligation on 19.\" the part of Sun Microsystems, Inc. to assist in its use, correction, 20.\" modification or enhancement. 21.\" 22.\" SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE 23.\" INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS 24.\" SOURCE CODE OR ANY PART THEREOF. 25.\" 26.\" Sun Microsystems, Inc. 27.\" 2550 Garcia Avenue 28.\" Mountain View, California 94043 29.\" 30.\" Copyright (c) 1991 Sun Microsystems, Inc. 31.\" 32.Dd May 7, 2024 33.Dt DLOPEN 3 34.Os 35.Sh NAME 36.Nm dlopen , 37.Nm fdlopen , 38.Nm dlsym , 39.Nm dlvsym , 40.Nm dlfunc , 41.Nm dlerror , 42.Nm dlclose 43.Nd programmatic interface to the dynamic linker 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.In dlfcn.h 48.Ft void * 49.Fn dlopen "const char *path" "int mode" 50.Ft void * 51.Fn fdlopen "int fd" "int mode" 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 * restrict version" 56.Ft dlfunc_t 57.Fn dlfunc "void * restrict handle" "const char * restrict symbol" 58.Ft char * 59.Fn dlerror "void" 60.Ft int 61.Fn dlclose "void *handle" 62.Sh DESCRIPTION 63These functions provide a simple programmatic interface to the services of the 64dynamic linker. 65Operations are provided to add new shared objects to a 66program's address space, to obtain the address bindings of symbols 67defined by such 68objects, and to remove such objects when their use is no longer required. 69.Pp 70The 71.Fn dlopen 72function 73provides access to the shared object in 74.Fa path , 75returning a descriptor that can be used for later 76references to the object in calls to 77.Fn dlsym , 78.Fn dlvsym 79and 80.Fn dlclose . 81If 82.Fa path 83was not in the address space prior to the call to 84.Fn dlopen , 85it is placed in the address space. 86When an object is first loaded into the address space in this way, its 87function 88.Fn _init , 89if any, is called by the dynamic linker. 90If 91.Fa path 92has already been placed in the address space in a previous call to 93.Fn dlopen , 94it is not added a second time, although a reference count of 95.Fn dlopen 96operations on 97.Fa path 98is maintained. 99A null pointer supplied for 100.Fa path 101is interpreted as a reference to the main 102executable of the process. 103The 104.Fa mode 105argument 106controls the way in which external function references from the 107loaded object are bound to their referents. 108It must contain one of the following values, possibly ORed with 109additional flags which will be described subsequently: 110.Bl -tag -width RTLD_LAZYX 111.It Dv RTLD_LAZY 112Each external function reference is resolved when the function is first 113called. 114.It Dv RTLD_NOW 115All external function references are bound immediately by 116.Fn dlopen . 117.El 118.Pp 119.Dv RTLD_LAZY 120is normally preferred, for reasons of efficiency. 121However, 122.Dv RTLD_NOW 123is useful to ensure that any undefined symbols are discovered during the 124call to 125.Fn dlopen . 126.Pp 127One of the following flags may be ORed into the 128.Fa mode 129argument: 130.Bl -tag -width RTLD_NODELETE 131.It Dv RTLD_GLOBAL 132Symbols from this shared object and its directed acyclic graph (DAG) 133of needed objects will be available for resolving undefined references 134from all other shared objects. 135.It Dv RTLD_LOCAL 136Symbols in this shared object and its DAG of needed objects will be 137available for resolving undefined references only from other objects 138in the same DAG. 139This is the default, but it may be specified 140explicitly with this flag. 141.It Dv RTLD_TRACE 142When set, causes dynamic linker to exit after loading all objects 143needed by this shared object and printing a summary which includes 144the absolute pathnames of all objects, to standard output. 145With this flag 146.Fn dlopen 147will return to the caller only in the case of error. 148.It Dv RTLD_NODELETE 149Prevents unload of the loaded object on 150.Fn dlclose . 151The same behaviour may be requested by 152.Fl "z nodelete" 153option of the static linker 154.Xr ld 1 . 155.It Dv RTLD_NOLOAD 156Only return valid handle for the object if it is already loaded in 157the process address space, otherwise 158.Dv NULL 159is returned. 160Other mode flags may be specified, which will be applied for promotion 161for the found object. 162.It Dv RTLD_DEEPBIND 163Symbols from the loaded library are put before global symbols when 164resolving symbolic references originated from the library. 165.El 166.Pp 167A special syntax for the 168.Fa path 169is supported, in the form of 170.Dl #number/name . 171The 172.Ql number 173should be a decimal number, which references an open file descriptor, 174and which must be also listed in the environment variable 175.Ev LD_LIBRARY_PATH_FDS . 176In this case, the linker tries to load an object that can be opened by 177.Ql openat(number, path, O_RDONLY) . 178This feature is only available to trusted processes, i.e., 179the activated image must be not set-uid or set-gid. 180.Pp 181If 182.Fn dlopen 183fails, it returns a null pointer, and sets an error condition which may 184be interrogated with 185.Fn dlerror . 186.Pp 187The 188.Fn fdlopen 189function is similar to 190.Fn dlopen , 191but it takes the file descriptor argument 192.Fa fd , 193which is used for the file operations needed to load an object 194into the address space. 195The file descriptor 196.Fa fd 197is not closed by the function regardless a result of execution, 198but a duplicate of the file descriptor is. 199This may be important if a 200.Xr lockf 3 201lock is held on the passed descriptor. 202The 203.Fa fd 204argument -1 is interpreted as a reference to the main 205executable of the process, similar to 206.Va NULL 207value for the 208.Fa name 209argument to 210.Fn dlopen . 211The 212.Fn fdlopen 213function can be used by the code that needs to perform 214additional checks on the loaded objects, to prevent races with 215symlinking or renames. 216Applications sandboxed using 217.Xr capsicum 4 218can also make beneficial use of 219.Fn fdlopen . 220.Pp 221The 222.Fn dlsym 223function 224returns the address binding of the symbol described in the null-terminated 225character string 226.Fa symbol , 227as it occurs in the shared object identified by 228.Fa handle . 229The symbols exported by objects added to the address space by 230.Fn dlopen 231can be accessed only through calls to 232.Fn dlsym . 233Such symbols do not supersede any definition of those symbols already present 234in the address space when the object is loaded, nor are they available to 235satisfy normal dynamic linking references. 236.Pp 237If 238.Fn dlsym 239is called with the special 240.Fa handle 241.Dv NULL , 242it is interpreted as a reference to the executable or shared object 243from which the call 244is being made. 245Thus a shared object can reference its own symbols. 246.Pp 247If 248.Fn dlsym 249is called with the special 250.Fa handle 251.Dv RTLD_DEFAULT , 252the search for the symbol follows the algorithm used for resolving 253undefined symbols when objects are loaded. 254The objects searched are 255as follows, in the given order: 256.Bl -enum 257.It 258The referencing object itself (or the object from which the call to 259.Fn dlsym 260is made), if that object was linked using the 261.Fl Bsymbolic 262option to 263.Xr ld 1 . 264.It 265All objects loaded at program start-up. 266.It 267All objects loaded via 268.Fn dlopen 269with the 270.Dv RTLD_GLOBAL 271flag set in the 272.Fa mode 273argument. 274.It 275All objects loaded via 276.Fn dlopen 277which are in needed-object DAGs that also contain the referencing object. 278.El 279.Pp 280If 281.Fn dlsym 282is called with the special 283.Fa handle 284.Dv RTLD_NEXT , 285then the search for the symbol is limited to the shared objects 286which were loaded after the one issuing the call to 287.Fn dlsym . 288Thus, if the function is called from the main program, all 289the shared libraries are searched. 290If it is called from a shared library, all subsequent shared 291libraries are searched. 292.Dv RTLD_NEXT 293is useful for implementing wrappers around library functions. 294For example, a wrapper function 295.Fn getpid 296could access the 297.Dq real 298.Fn getpid 299with 300.Li dlsym(RTLD_NEXT, \&"getpid\&") . 301(Actually, the 302.Fn dlfunc 303interface, below, should be used, since 304.Fn getpid 305is a function and not a data object.) 306.Pp 307If 308.Fn dlsym 309is called with the special 310.Fa handle 311.Dv RTLD_SELF , 312then the search for the symbol is limited to the shared object 313issuing the call to 314.Fn dlsym 315and those shared objects which were loaded after it. 316.Pp 317The 318.Fn dlsym 319function 320returns a null pointer if the symbol cannot be found, and sets an error 321condition which may be queried with 322.Fn dlerror . 323.Pp 324The 325.Fn dlvsym 326function behaves like 327.Fn dlsym , 328but takes an extra argument 329.Fa version : 330a null-terminated character string which is used to request a specific version 331of 332.Fa symbol . 333.Pp 334The 335.Fn dlfunc 336function 337implements all of the behavior of 338.Fn dlsym , 339but has a return type which can be cast to a function pointer without 340triggering compiler diagnostics. 341(The 342.Fn dlsym 343function 344returns an object pointer; in the C standard, conversions between 345object and function pointer types are undefined. 346Some compilers and lint utilities warn about such casts.) 347The precise return type of 348.Fn dlfunc 349is unspecified; applications must cast it to an appropriate function pointer 350type. 351.Pp 352The 353.Fn dlerror 354function 355returns a null-terminated character string describing the last error that 356occurred during a call to 357.Fn dlopen , 358.Fn dladdr , 359.Fn dlinfo , 360.Fn dlsym , 361.Fn dlvsym , 362.Fn dlfunc , 363or 364.Fn dlclose . 365If no such error has occurred, 366.Fn dlerror 367returns a null pointer. 368At each call to 369.Fn dlerror , 370the error indication is reset. 371Thus in the case of two calls 372to 373.Fn dlerror , 374where the second call follows the first immediately, the second call 375will always return a null pointer. 376.Pp 377The 378.Fn dlclose 379function 380deletes a reference to the shared object referenced by 381.Fa handle . 382If the reference count drops to 0, the object is removed from the 383address space, and 384.Fa handle 385is rendered invalid. 386Just before removing a shared object in this way, the dynamic linker 387calls the object's 388.Fn _fini 389function, if such a function is defined by the object. 390If 391.Fn dlclose 392is successful, it returns a value of 0. 393Otherwise it returns -1, and sets an error condition that can be 394interrogated with 395.Fn dlerror . 396.Pp 397The object-intrinsic functions 398.Fn _init 399and 400.Fn _fini 401are called with no arguments, and are not expected to return values. 402.Sh NOTES 403ELF executables need to be linked 404using the 405.Fl export-dynamic 406option to 407.Xr ld 1 408for symbols defined in the executable to become visible to 409.Fn dlsym , 410.Fn dlvsym 411or 412.Fn dlfunc 413.Pp 414Other ELF platforms require linking with 415.Lb libdl 416to provide 417.Fn dlopen 418and other functions. 419.Fx 420does not require linking with the library, but supports it for compatibility. 421.Pp 422In previous implementations, it was necessary to prepend an underscore 423to all external symbols in order to gain symbol 424compatibility with object code compiled from the C language. 425This is 426still the case when using the (obsolete) 427.Fl aout 428option to the C language compiler. 429.Sh ERRORS 430The 431.Fn dlopen , 432.Fn fdlopen , 433.Fn dlsym , 434.Fn dlvsym , 435and 436.Fn dlfunc 437functions 438return a null pointer in the event of errors. 439The 440.Fn dlclose 441function 442returns 0 on success, or -1 if an error occurred. 443Whenever an error has been detected, a message detailing it can be 444retrieved via a call to 445.Fn dlerror . 446.Sh SEE ALSO 447.Xr ld 1 , 448.Xr rtld 1 , 449.Xr dladdr 3 , 450.Xr dlinfo 3 , 451.Xr link 5 452