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