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