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 September 24, 1989 36.Os FreeBSD 37.Dt DLOPEN 3 38.Sh NAME 39.Nm dlopen, dlsym, dlerror, dlclose 40.Nd programmatic interface to the dynamic linker 41.Sh SYNOPSIS 42.Fd #include <dlfcn.h> 43.Ft void * 44.Fn dlopen "const char *path" "int mode" 45.Ft void * 46.Fn dlsym "void *handle" "const char *symbol" 47.Ft const char * 48.Fn dlerror "void" 49.Ft int 50.Fn dlclose "void *handle" 51.Sh DESCRIPTION 52These functions provide a simple programmatic interface to the services of the 53dynamic linker. 54Operations are provided to add new shared objects to a 55program's address space, to obtain the address bindings of symbols 56defined by such 57objects, and to remove such objects when their use is no longer required. 58.Pp 59.Fn dlopen 60provides access to the shared object in 61.Fa path , 62returning a descriptor that can be used for later 63references to the object in calls to 64.Fn dlsym 65and 66.Fn dlclose . 67If 68.Fa path 69was not in the address space prior to the call to 70.Fn dlopen , 71it is placed in the address space. 72When an object is first loaded into the address space in this way, its 73function 74.Fn _init , 75if any, is called by the dynamic linker. 76If 77.Fa path 78has already been placed in the address space in a previous call to 79.Fn dlopen , 80it is not added a second time, although a reference count of 81.Fn dlopen 82operations on 83.Fa path 84is maintained. 85A null pointer supplied for 86.Fa path 87is interpreted as a reference to the main 88executable of the process. 89.Fa mode 90controls the way in which external function references from the 91loaded object are bound to their referents. 92It must contain one of the following values: 93.Bl -tag -width RTLD_LAZYX 94.It Dv RTLD_LAZY 95Each external function reference is resolved when the function is first 96called. 97.It Dv RTLD_NOW 98All external function references are bound immediately by 99.Fn dlopen . 100.El 101.Pp 102.Dv RTLD_LAZY 103is normally preferred, for reasons of efficiency. 104However, 105.Dv RTLD_NOW 106is useful to ensure that any undefined symbols are discovered during the 107call to 108.Fn dlopen . 109If 110.Fn dlopen 111fails, it returns a null pointer, and sets an error condition which may 112be interrogated with 113.Fn dlerror . 114.Pp 115.Fn dlsym 116returns the address binding of the symbol described in the null-terminated 117character string 118.Fa symbol , 119as it occurs in the shared object identified by 120.Fa handle . 121The symbols exported by objects added to the address space by 122.Fn dlopen 123can be accessed only through calls to 124.Fn dlsym . 125Such symbols do not supersede any definition of those symbols already present 126in the address space when the object is loaded, nor are they available to 127satisfy normal dynamic linking references. 128A null pointer supplied as the value of 129.Fa handle 130is interpreted as a reference to the executable from which the call to 131.Fn dlsym 132is being made. Thus a shared object can reference its own symbols. 133.Fn dlsym 134returns a null pointer if the symbol cannot be found, and sets an error 135condition which may be queried with 136.Fn dlerror . 137.Pp 138If 139.Fn dlsym 140is called with the special 141.Fa handle 142.Dv RTLD_NEXT , 143then the search for the symbol is limited to the shared objects 144which were loaded after the one issuing the call to 145.Fn dlsym . 146Thus, if the function is called from the main program, all 147the shared libraries are searched. 148If it is called from a shared library, all subsequent shared 149libraries are searched. 150.Dv RTLD_NEXT 151is useful for implementing wrappers around library functions. 152For example, a wrapper function 153.Fn getpid 154could access the 155.Dq real 156.Fn getpid 157with 158.Li dlsym(RTLD_NEXT, \&"getpid\&") . 159.Pp 160.Fn dlerror 161returns a null-terminated character string describing the last error that 162occurred during a call to 163.Fn dlopen , 164.Fn dlsym , 165or 166.Fn dlclose . 167If no such error has occurred, 168.Fn dlerror 169returns a null pointer. 170At each call to 171.Fn dlerror , 172the error indication is reset. Thus in the case of two calls 173to 174.Fn dlerror , 175where the second call follows the first immediately, the second call 176will always return a null pointer. 177.Pp 178.Fn dlclose 179deletes a reference to the shared object referenced by 180.Fa handle . 181If the reference count drops to 0, the object is removed from the 182address space, and 183.Fa handle 184is rendered invalid. 185Just before removing a shared object in this way, the dynamic linker 186calls the object's 187.Fn _fini 188function, if such a function is defined by the object. 189If 190.Fn dlclose 191is successful, it returns a value of 0. 192Otherwise it returns -1, and sets an error condition that can be 193interrogated with 194.Fn dlerror . 195.Pp 196The object-intrinsic functions 197.Fn _init 198and 199.Fn _fini 200are called with no arguments, and are not expected to return values. 201.Sh NOTES 202ELF executables need to be linked 203using the 204.Fl export-dynamic 205option to 206.Xr ld 1 207for symbols defined in the executable to become visible to 208.Fn dlsym . 209.Pp 210In previous implementations, it was necessary to prepend an underscore 211to all external symbols in order to gain symbol 212compatibility with object code compiled from the C language. This is 213still the case when using the (obsolete) 214.Fl aout 215option to the C language compiler. 216.Sh ERRORS 217.Fn dlopen 218and 219.Fn dlsym 220return the null pointer in the event of errors. 221.Fn dlclose 222returns 0 on success, or -1 if an error occurred. 223Whenever an error has been detected, a message detailing it can be 224retrieved via a call to 225.Fn dlerror . 226.Sh SEE ALSO 227.Xr ld 1 , 228.Xr rtld 1 , 229.Xr link 5 230 231