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 167If 168.Fn dlopen 169fails, it returns a null pointer, and sets an error condition which may 170be interrogated with 171.Fn dlerror . 172.Pp 173The 174.Fn fdlopen 175function is similar to 176.Fn dlopen , 177but it takes the file descriptor argument 178.Fa fd , 179which is used for the file operations needed to load an object 180into the address space. 181The file descriptor 182.Fa fd 183is not closed by the function regardless a result of execution, 184but a duplicate of the file descriptor is. 185This may be important if a 186.Xr lockf 3 187lock is held on the passed descriptor. 188The 189.Fa fd 190argument -1 is interpreted as a reference to the main 191executable of the process, similar to 192.Va NULL 193value for the 194.Fa name 195argument to 196.Fn dlopen . 197The 198.Fn fdlopen 199function can be used by the code that needs to perform 200additional checks on the loaded objects, to prevent races with 201symlinking or renames. 202Applications sandboxed using 203.Xr capsicum 4 204can also make beneficial use of 205.Fn fdlopen . 206.Pp 207The 208.Fn dlsym 209function 210returns the address binding of the symbol described in the null-terminated 211character string 212.Fa symbol , 213as it occurs in the shared object identified by 214.Fa handle . 215The symbols exported by objects added to the address space by 216.Fn dlopen 217can be accessed only through calls to 218.Fn dlsym . 219Such symbols do not supersede any definition of those symbols already present 220in the address space when the object is loaded, nor are they available to 221satisfy normal dynamic linking references. 222.Pp 223If 224.Fn dlsym 225is called with the special 226.Fa handle 227.Dv NULL , 228it is interpreted as a reference to the executable or shared object 229from which the call 230is being made. 231Thus a shared object can reference its own symbols. 232.Pp 233If 234.Fn dlsym 235is called with the special 236.Fa handle 237.Dv RTLD_DEFAULT , 238the search for the symbol follows the algorithm used for resolving 239undefined symbols when objects are loaded. 240The objects searched are 241as follows, in the given order: 242.Bl -enum 243.It 244The referencing object itself (or the object from which the call to 245.Fn dlsym 246is made), if that object was linked using the 247.Fl Bsymbolic 248option to 249.Xr ld 1 . 250.It 251All objects loaded at program start-up. 252.It 253All objects loaded via 254.Fn dlopen 255with the 256.Dv RTLD_GLOBAL 257flag set in the 258.Fa mode 259argument. 260.It 261All objects loaded via 262.Fn dlopen 263which are in needed-object DAGs that also contain the referencing object. 264.El 265.Pp 266If 267.Fn dlsym 268is called with the special 269.Fa handle 270.Dv RTLD_NEXT , 271then the search for the symbol is limited to the shared objects 272which were loaded after the one issuing the call to 273.Fn dlsym . 274Thus, if the function is called from the main program, all 275the shared libraries are searched. 276If it is called from a shared library, all subsequent shared 277libraries are searched. 278.Dv RTLD_NEXT 279is useful for implementing wrappers around library functions. 280For example, a wrapper function 281.Fn getpid 282could access the 283.Dq real 284.Fn getpid 285with 286.Li dlsym(RTLD_NEXT, \&"getpid\&") . 287(Actually, the 288.Fn dlfunc 289interface, below, should be used, since 290.Fn getpid 291is a function and not a data object.) 292.Pp 293If 294.Fn dlsym 295is called with the special 296.Fa handle 297.Dv RTLD_SELF , 298then the search for the symbol is limited to the shared object 299issuing the call to 300.Fn dlsym 301and those shared objects which were loaded after it. 302.Pp 303The 304.Fn dlsym 305function 306returns a null pointer if the symbol cannot be found, and sets an error 307condition which may be queried with 308.Fn dlerror . 309.Pp 310The 311.Fn dlvsym 312function behaves like 313.Fn dlsym , 314but takes an extra argument 315.Fa version : 316a null-terminated character string which is used to request a specific version 317of 318.Fa symbol . 319.Pp 320The 321.Fn dlfunc 322function 323implements all of the behavior of 324.Fn dlsym , 325but has a return type which can be cast to a function pointer without 326triggering compiler diagnostics. 327(The 328.Fn dlsym 329function 330returns an object pointer; in the C standard, conversions between 331object and function pointer types are undefined. 332Some compilers and lint utilities warn about such casts.) 333The precise return type of 334.Fn dlfunc 335is unspecified; applications must cast it to an appropriate function pointer 336type. 337.Pp 338The 339.Fn dlerror 340function 341returns a null-terminated character string describing the last error that 342occurred during a call to 343.Fn dlopen , 344.Fn dladdr , 345.Fn dlinfo , 346.Fn dlsym , 347.Fn dlvsym , 348.Fn dlfunc , 349or 350.Fn dlclose . 351If no such error has occurred, 352.Fn dlerror 353returns a null pointer. 354At each call to 355.Fn dlerror , 356the error indication is reset. 357Thus in the case of two calls 358to 359.Fn dlerror , 360where the second call follows the first immediately, the second call 361will always return a null pointer. 362.Pp 363The 364.Fn dlclose 365function 366deletes a reference to the shared object referenced by 367.Fa handle . 368If the reference count drops to 0, the object is removed from the 369address space, and 370.Fa handle 371is rendered invalid. 372Just before removing a shared object in this way, the dynamic linker 373calls the object's 374.Fn _fini 375function, if such a function is defined by the object. 376If 377.Fn dlclose 378is successful, it returns a value of 0. 379Otherwise it returns -1, and sets an error condition that can be 380interrogated with 381.Fn dlerror . 382.Pp 383The object-intrinsic functions 384.Fn _init 385and 386.Fn _fini 387are called with no arguments, and are not expected to return values. 388.Sh NOTES 389ELF executables need to be linked 390using the 391.Fl export-dynamic 392option to 393.Xr ld 1 394for symbols defined in the executable to become visible to 395.Fn dlsym , 396.Fn dlvsym 397or 398.Fn dlfunc 399.Pp 400Other ELF platforms require linking with 401.Lb libdl 402to provide 403.Fn dlopen 404and other functions. 405.Fx 406does not require linking with the library, but supports it for compatibility. 407.Pp 408In previous implementations, it was necessary to prepend an underscore 409to all external symbols in order to gain symbol 410compatibility with object code compiled from the C language. 411This is 412still the case when using the (obsolete) 413.Fl aout 414option to the C language compiler. 415.Sh ERRORS 416The 417.Fn dlopen , 418.Fn fdlopen , 419.Fn dlsym , 420.Fn dlvsym , 421and 422.Fn dlfunc 423functions 424return a null pointer in the event of errors. 425The 426.Fn dlclose 427function 428returns 0 on success, or -1 if an error occurred. 429Whenever an error has been detected, a message detailing it can be 430retrieved via a call to 431.Fn dlerror . 432.Sh SEE ALSO 433.Xr ld 1 , 434.Xr rtld 1 , 435.Xr dladdr 3 , 436.Xr dlinfo 3 , 437.Xr link 5 438