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. 76(Note that 77.Ql _init 78is the name as expressed in the C language. 79From assembly language, the name would appear as 80.Ql __init 81instead.) 82If 83.Fa path 84has already been placed in the address space in a previous call to 85.Fn dlopen , 86it is not added a second time, although a reference count of 87.Fn dlopen 88operations on 89.Fa path 90is maintained. 91A null pointer supplied for 92.Fa path 93is interpreted as a reference to the main 94executable of the process. 95.Fa mode 96controls the way in which external function references from the 97loaded object are bound to their referents. 98It must contain one of the following values: 99.Bl -tag -width RTLD_LAZYX 100.It Dv RTLD_LAZY 101Each external function reference is resolved when the function is first 102called. 103.It Dv RTLD_NOW 104All external function references are bound immediately by 105.Fn dlopen . 106.El 107.Pp 108.Dv RTLD_LAZY 109is normally preferred, for reasons of efficiency. 110However, 111.Dv RTLD_NOW 112is useful to ensure that any undefined symbols are discovered during the 113call to 114.Fn dlopen . 115If 116.Fn dlopen 117fails, it returns a null pointer, and sets an error condition which may 118be interrogated with 119.Fn dlerror . 120.Pp 121.Fn dlsym 122returns the address binding of the symbol described in the null-terminated 123character string 124.Fa symbol , 125as it occurs in the shared object identified by 126.Fa handle . 127Note that 128.Fa symbol 129is the assembly language representation of the symbol name. 130The assembly language representation of a C language symbol contains an 131extra underscore at the beginning. 132For example, the symbol 133.Ql foo 134in C would appear as 135.Ql _foo 136in assembly language, and in the 137.Fa symbol 138argument to 139.Fn dlsym . 140The symbols exported by objects added to the address space by 141.Fn dlopen 142can be accessed only through calls to 143.Fn dlsym . 144Such symbols do not supersede any definition of those symbols already present 145in the address space when the object is loaded, nor are they available to 146satisfy normal dynamic linking references. 147A null pointer supplied as the value of 148.Fa handle 149is interpreted as a reference to the executable from which the call to 150.Fn dlsym 151is being made. Thus a shared object can reference its own symbols. 152.Fn dlsym 153returns a null pointer if the symbol cannot be found, and sets an error 154condition which may be queried with 155.Fn dlerror . 156.Pp 157If 158.Fn dlsym 159is called with the special 160.Fa handle 161.Dv RTLD_NEXT , 162then the search for the symbol is limited to the shared objects 163which were loaded after the one issuing the call to 164.Fn dlsym . 165Thus, if the function is called from the main program, all 166the shared libraries are searched. 167If it is called from a shared library, all subsequent shared 168libraries are searched. 169.Dv RTLD_NEXT 170is useful for implementing wrappers around library functions. 171For example, a wrapper function 172.Fn getpid 173could access the 174.Dq real 175.Fn getpid 176with 177.Li dlsym(RTLD_NEXT, \&"_getpid\&") . 178.Pp 179.Fn dlerror 180returns a null-terminated character string describing the last error that 181occurred during a call to 182.Fn dlopen , 183.Fn dlsym , 184or 185.Fn dlclose . 186If no such error has occurred, 187.Fn dlerror 188returns a null pointer. 189At each call to 190.Fn dlerror , 191the error indication is reset. Thus in the case of two calls 192to 193.Fn dlerror , 194where the second call follows the first immediately, the second call 195will always return a null pointer. 196.Pp 197.Fn dlclose 198deletes a reference to the shared object referenced by 199.Fa handle . 200If the reference count drops to 0, the object is removed from the 201address space, and 202.Fa handle 203is rendered invalid. 204Just before removing a shared object in this way, the dynamic linker 205calls the object's 206.Fn _fini 207function, if such a function is defined by the object. 208As with 209.Ql _init , 210.Ql _fini 211is the C language name of the function. 212If 213.Fn dlclose 214is successful, it returns a value of 0. 215Otherwise it returns -1, and sets an error condition that can be 216interrogated with 217.Fn dlerror . 218.Pp 219The object-intrinsic functions 220.Fn _init 221and 222.Fn _fini 223are called with no arguments, and are not expected to return values. 224.Sh NOTES 225ELF executables need to be linked 226using the 227.Fl export-dynamic 228option to 229.Xr ld 1 230for symbols defined in the executable to become visible to 231.Fn dlsym . 232.Sh ERRORS 233.Fn dlopen 234and 235.Fn dlsym 236return the null pointer in the event of errors. 237.Fn dlclose 238returns 0 on success, or -1 if an error occurred. 239Whenever an error has been detected, a message detailing it can be 240retrieved via a call to 241.Fn dlerror . 242.Sh SEE ALSO 243.Xr ld 1 , 244.Xr rtld 1 , 245.Xr link 5 246 247