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