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: src/lib/libc/gen/dlopen.3,v 1.8.2.10 2003/03/15 15:11:05 trhodes Exp $ 34.\" $DragonFly: src/lib/libc/gen/dlopen.3,v 1.2 2003/06/17 04:26:42 dillon Exp $ 35.\" 36.Dd September 24, 1989 37.Os 38.Dt DLOPEN 3 39.Sh NAME 40.Nm dlopen , 41.Nm dlsym , 42.Nm dlerror , 43.Nm dlclose 44.Nd programmatic interface to the dynamic linker 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In dlfcn.h 49.Ft void * 50.Fn dlopen "const char *path" "int mode" 51.Ft void * 52.Fn dlsym "void *handle" "const char *symbol" 53.Ft const char * 54.Fn dlerror "void" 55.Ft int 56.Fn dlclose "void *handle" 57.Sh DESCRIPTION 58These functions provide a simple programmatic interface to the services of the 59dynamic linker. 60Operations are provided to add new shared objects to a 61program's address space, to obtain the address bindings of symbols 62defined by such 63objects, and to remove such objects when their use is no longer required. 64.Pp 65The 66.Fn dlopen 67function 68provides access to the shared object in 69.Fa path , 70returning a descriptor that can be used for later 71references to the object in calls to 72.Fn dlsym 73and 74.Fn dlclose . 75If 76.Fa path 77was not in the address space prior to the call to 78.Fn dlopen , 79it is placed in the address space. 80When an object is first loaded into the address space in this way, its 81function 82.Fn _init , 83if any, is called by the dynamic linker. 84If 85.Fa path 86has already been placed in the address space in a previous call to 87.Fn dlopen , 88it is not added a second time, although a reference count of 89.Fn dlopen 90operations on 91.Fa path 92is maintained. 93A null pointer supplied for 94.Fa path 95is interpreted as a reference to the main 96executable of the process. 97The 98.Fa mode 99argument 100controls the way in which external function references from the 101loaded object are bound to their referents. 102It must contain one of the following values, possibly ORed with 103additional flags which will be described subsequently: 104.Bl -tag -width RTLD_LAZYX 105.It Dv RTLD_LAZY 106Each external function reference is resolved when the function is first 107called. 108.It Dv RTLD_NOW 109All external function references are bound immediately by 110.Fn dlopen . 111.El 112.Pp 113.Dv RTLD_LAZY 114is normally preferred, for reasons of efficiency. 115However, 116.Dv RTLD_NOW 117is useful to ensure that any undefined symbols are discovered during the 118call to 119.Fn dlopen . 120.Pp 121One of the following flags may be ORed into the 122.Fa mode 123argument: 124.Bl -tag -width RTLD_GLOBALX 125.It Dv RTLD_GLOBAL 126Symbols from this shared object and its directed acyclic graph (DAG) 127of needed objects will be available for resolving undefined references 128from all other shared objects. 129.It Dv RTLD_LOCAL 130Symbols in this shared object and its DAG of needed objects will be 131available for resolving undefined references only from other objects 132in the same DAG. 133This is the default, but it may be specified 134explicitly with this flag. 135.It Dv RTLD_TRACE 136When set, causes dynamic linker to exit after loading all objects 137needed by this shared object and printing a summary which includes 138the absolute pathnames of all objects, to standard output. 139With this flag 140.Fn dlopen 141will return to the caller only in the case of error. 142.El 143.Pp 144If 145.Fn dlopen 146fails, it returns a null pointer, and sets an error condition which may 147be interrogated with 148.Fn dlerror . 149.Pp 150The 151.Fn dlsym 152function 153returns the address binding of the symbol described in the null-terminated 154character string 155.Fa symbol , 156as it occurs in the shared object identified by 157.Fa handle . 158The symbols exported by objects added to the address space by 159.Fn dlopen 160can be accessed only through calls to 161.Fn dlsym . 162Such symbols do not supersede any definition of those symbols already present 163in the address space when the object is loaded, nor are they available to 164satisfy normal dynamic linking references. 165.Pp 166If 167.Fn dlsym 168is called with the special 169.Fa handle 170.Dv NULL , 171it is interpreted as a reference to the executable or shared object 172from which the call 173is being made. 174Thus a shared object can reference its own symbols. 175.Pp 176If 177.Fn dlsym 178is called with the special 179.Fa handle 180.Dv RTLD_DEFAULT , 181the search for the symbol follows the algorithm used for resolving 182undefined symbols when objects are loaded. 183The objects searched are 184as follows, in the given order: 185.Bl -enum 186.It 187The referencing object itself (or the object from which the call to 188.Fn dlsym 189is made), if that object was linked using the 190.Fl Wsymbolic 191option to 192.Xr ld 1 . 193.It 194All objects loaded at program start-up. 195.It 196All objects loaded via 197.Fn dlopen 198which are in needed-object DAGs that also contain the referencing object. 199.It 200All objects loaded via 201.Fn dlopen 202with the 203.Dv RTLD_GLOBAL 204flag set in the 205.Fa mode 206argument. 207.El 208.Pp 209If 210.Fn dlsym 211is called with the special 212.Fa handle 213.Dv RTLD_NEXT , 214then the search for the symbol is limited to the shared objects 215which were loaded after the one issuing the call to 216.Fn dlsym . 217Thus, if the function is called from the main program, all 218the shared libraries are searched. 219If it is called from a shared library, all subsequent shared 220libraries are searched. 221.Dv RTLD_NEXT 222is useful for implementing wrappers around library functions. 223For example, a wrapper function 224.Fn getpid 225could access the 226.Dq real 227.Fn getpid 228with 229.Li dlsym(RTLD_NEXT, \&"getpid\&") . 230.Pp 231If 232.Fn dlsym 233is called with the special 234.Fa handle 235.Dv RTLD_SELF , 236then the search for the symbol is limited to the shared object 237issuing the call to 238.Fn dlsym 239and those shared objects which were loaded after it. 240.Pp 241The 242.Fn dlsym 243function 244returns a null pointer if the symbol cannot be found, and sets an error 245condition which may be queried with 246.Fn dlerror . 247.Pp 248The 249.Fn dlerror 250function 251returns a null-terminated character string describing the last error that 252occurred during a call to 253.Fn dlopen , 254.Fn dladdr , 255.Fn dlinfo , 256.Fn dlsym , 257or 258.Fn dlclose . 259If no such error has occurred, 260.Fn dlerror 261returns a null pointer. 262At each call to 263.Fn dlerror , 264the error indication is reset. 265Thus in the case of two calls 266to 267.Fn dlerror , 268where the second call follows the first immediately, the second call 269will always return a null pointer. 270.Pp 271The 272.Fn dlclose 273function 274deletes a reference to the shared object referenced by 275.Fa handle . 276If the reference count drops to 0, the object is removed from the 277address space, and 278.Fa handle 279is rendered invalid. 280Just before removing a shared object in this way, the dynamic linker 281calls the object's 282.Fn _fini 283function, if such a function is defined by the object. 284If 285.Fn dlclose 286is successful, it returns a value of 0. 287Otherwise it returns -1, and sets an error condition that can be 288interrogated with 289.Fn dlerror . 290.Pp 291The object-intrinsic functions 292.Fn _init 293and 294.Fn _fini 295are called with no arguments, and are not expected to return values. 296.Sh NOTES 297ELF executables need to be linked 298using the 299.Fl export-dynamic 300option to 301.Xr ld 1 302for symbols defined in the executable to become visible to 303.Fn dlsym . 304.Pp 305In previous implementations, it was necessary to prepend an underscore 306to all external symbols in order to gain symbol 307compatibility with object code compiled from the C language. 308This is 309still the case when using the (obsolete) 310.Fl aout 311option to the C language compiler. 312.Sh ERRORS 313The 314.Fn dlopen 315and 316.Fn dlsym 317functions 318return a null pointer in the event of errors. 319The 320.Fn dlclose 321function 322returns 0 on success, or -1 if an error occurred. 323Whenever an error has been detected, a message detailing it can be 324retrieved via a call to 325.Fn dlerror . 326.Sh SEE ALSO 327.Xr ld 1 , 328.Xr rtld 1 , 329.Xr dladdr 3 , 330.Xr dlinfo 3 , 331.Xr link 5 332