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