1.\" $NetBSD: dlfcn.3,v 1.30 2010/12/24 13:00:24 wiz Exp $ 2.\" 3.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd December 24, 2010 31.Dt DLFCN 3 32.Os 33.Sh NAME 34.Nm dlopen , 35.Nm dlclose , 36.Nm dlsym , 37.Nm dladdr , 38.Nm dlctl , 39.Nm dlerror 40.Nd dynamic link interface 41.Sh LIBRARY 42(These functions are not in a library. 43They are included in every 44dynamically linked program automatically.) 45.Sh SYNOPSIS 46.In dlfcn.h 47.Ft "void *" 48.Fn dlopen "const char *path" "int mode" 49.Ft "int" 50.Fn dlclose "void *handle" 51.Ft "void *" 52.Fn dlsym "void * restrict handle" "const char * restrict symbol" 53.Ft "int" 54.Fn dladdr "void * restrict addr" "Dl_info * restrict dli" 55.Ft "int" 56.Fn dlctl "void *handle" "int cmd" "void *data" 57.Ft "char *" 58.Fn dlerror "void" 59.Sh DESCRIPTION 60These functions provide an interface to the run-time linker 61.Xr ld.so 1 . 62They allow new shared objects to be loaded into the process' address space 63under program control. 64.Pp 65The 66.Fn dlopen 67function takes the name of a shared object as the first argument. 68The 69.Fa path 70argument can be specified as either an absolute pathname to a shared object 71or just the name of the shared object itself. 72When an absolute pathname is specified, 73only the path provided will be searched. 74When just a shared object name is specified, the same search rules apply that 75are used for 76.Dq intrinsic 77shared object searches. 78.Po 79see 80.Xr ld.elf_so 1 81.Pc 82.Pp 83Shared libraries take the following form: 84.Do lib Ns Ao name Ac Ns .so Ns Oo .xx Ns Oo .yy Oc Oc Dc . 85.Pp 86The shared object is mapped into the address space, relocated, and 87its external references are resolved in the same way as is done 88with the implicitly loaded shared libraries at program startup. 89.Pp 90If the first argument is 91.Dv NULL , 92.Fn dlopen 93returns a 94.Fa handle 95on the global symbol object. 96This object 97provides access to all symbols from an ordered set of objects consisting 98of the original program image and any dependencies loaded during startup. 99.Pp 100The 101.Fa mode 102parameter specifies symbol resolution time and symbol visibility. 103One of the following values may be used to specify symbol resolution time: 104.Bl -tag -width "RTLD_GLOBALXX" -offset indent 105.It Dv RTLD_NOW 106Symbols are resolved immediately. 107.It Dv RTLD_LAZY 108Symbols are resolved when they are first referred to. 109This is the default value if resolution time is unspecified. 110.El 111.Pp 112One of the following values may be used to specify symbol visibility: 113.Pp 114.Bl -tag -width "RTLD_GLOBALXX" -offset indent 115.It Dv RTLD_GLOBAL 116The object's symbols and the symbols of its dependencies will be visible to 117other objects. 118.It Dv RTLD_LOCAL 119The object's symbols and the symbols of its dependencies will not be visible to 120other objects. 121This is the default value if visibility is unspecified. 122.El 123.Pp 124To specify both resolution time and visibility, bitwise inclusive OR one of 125each of the above values together. 126If an object was opened with 127.Dv RTLD_LOCAL 128and later opened with 129.Dv RTLD_GLOBAL , 130then it is promoted to 131.Dv RTLD_GLOBAL . 132.Pp 133Additionally, one of the following flags may be ORed into the 134.Fa mode 135argument: 136.Bl -tag -width "RTLD_NODELETEXX" -offset indent 137.It Dv RTLD_NODELETE 138Prevents unload of the loaded object on 139.Fn dlclose . 140The same behaviour may be requested by 141.Fl "z nodelete" 142option of the static linker 143.Xr ld 1 . 144.It Dv RTLD_NOLOAD 145Only return valid handle for the object if it is already loaded in 146the process address space, otherwise do not load the object and return 147.Dv NULL . 148.El 149.Pp 150.Fn dlopen 151returns a 152.Fa handle 153to be used in calls to 154.Fn dlclose , 155.Fn dlsym , 156and 157.Fn dlctl . 158If the named shared object has already 159been loaded by a previous call to 160.Fn dlopen 161.Pq and not yet unloaded by Fn dlclose , 162a 163.Fa handle 164referring to the resident copy is returned. 165.Pp 166.Fn dlclose 167unlinks and removes the object referred to by 168.Fa handle 169from the process address space. 170If multiple calls to 171.Fn dlopen 172have been done on this object, or the object was one loaded at startup time, 173or the object is a dependency of another object 174then the object is removed when its reference count drops to zero. 175.Fn dlclose 176returns 0 on success and non-zero on failure. 177.Pp 178.Fn dlsym 179looks for a definition of 180.Fa symbol 181in the shared object designated by 182.Fa handle , 183and all shared objects that are listed as dependencies. 184The symbol's address is returned. 185If the symbol cannot be resolved, 186.Dv NULL 187is returned. 188.Pp 189.Fn dlsym 190may also be called with special 191.Fa handle 192values. 193.Fn dlsym 194respects symbol visibility as specified by the 195.Fn dlopen 196.Fa mode 197parameter. 198However, the symbols of an object's dependencies are always visible to it. 199All shared objects loaded at program startup are globally visible. 200Only the symbols in the main executable that are referenced by a 201shared object at link time will be visible unless it has been linked 202with the --export-dynamic option where all of its symbols will be 203visible. 204The following special 205.Fa handle 206values may be used with 207.Fn dlsym : 208.Bl -tag -width "RTLD_DEFAULTXX" -offset indent 209.It Dv NULL 210Interpreted as a reference to the executable or shared object 211from which the call is being made. 212Thus an object can reference its own symbols and the symbols of its 213dependencies without calling 214.Fn dlopen . 215.It Dv RTLD_DEFAULT 216All the visible shared objects and the executable will be searched in the order 217they were loaded. 218.It Dv RTLD_NEXT 219The search for 220.Fa symbol 221is limited to the visible shared objects which were loaded after the one 222issuing the call to 223.Fn dlsym . 224Thus, if 225.Fn dlsym 226is called from the main program, all the visible shared libraries are searched. 227If it is called from a shared library, all subsequently visible shared 228libraries are searched. 229.It Dv RTLD_SELF 230The search for 231.Fa symbol 232is limited to the shared object issuing the call to 233.Fn dlsym 234and those shared objects which were loaded after it that are visible. 235.El 236.Pp 237.Fn dladdr 238examines all currently mapped shared objects for a symbol whose address -- 239as mapped in the process address space -- is closest to but not exceeding 240the value passed in the first argument 241.Fa addr . 242The symbols of a shared object are only eligible if 243.Va addr 244is between the base address of the shared object and the value of the 245symbol 246.Dq _end 247in the same shared object. 248If no object for which this condition holds 249true can be found, 250.Fn dladdr 251will return 0. 252Otherwise, a non-zero value is returned and the 253.Fa dli 254argument will be used to provide information on the selected symbol 255and the shared object it is contained in. 256The 257.Fa dli 258argument points at a caller-provided 259.Va Dl_info 260structure defined as follows: 261.Bd -literal -offset indent 262typedef struct { 263 const char *dli_fname; /* File defining the symbol */ 264 void *dli_fbase; /* Base address */ 265 const char *dli_sname; /* Symbol name */ 266 const void *dli_saddr; /* Symbol address */ 267} Dl_info; 268.Ed 269.Pp 270The structure members are further described as follows: 271.Bl -tag -width "dli_fnameXX" 272.It Li "dli_fname" 273The pathname of the shared object containing the address 274.Fa addr . 275.It Li "dli_fbase" 276The base address at which this shared object is loaded in the process 277address space. 278This may be zero if the symbol was found in the internally generated 279.Dq copy 280section 281.Po 282see 283.Xr link 5 284.Pc 285which is not associated with a file. 286.It Li "dli_sname" 287points at the nul-terminated name of the selected symbol 288.It Li "dli_saddr" 289is the actual address 290.Pq as it appears in the process address space 291of the symbol. 292.El 293.Pp 294Note: both strings pointed at by 295.Va dli_fname 296and 297.Va dli_sname 298reside in memory private to the run-time linker module and should not 299be modified by the caller. 300.Pp 301In dynamically linked programs, the address of a global function will 302point to its program linkage table entry, rather than to the entry 303point of the function itself. 304This causes most global functions to appear to be defined within the 305main executable, rather than in the shared libraries where the actual 306code resides. 307.Pp 308.Fn dlctl 309provides an interface similar to 310.Xr ioctl 2 311to control several aspects of the run-time linker's operation. 312This interface is 313.Ud 314.Pp 315.Fn dlerror 316returns a character string representing the most recent error that has 317occurred while processing one of the other functions described here. 318If no dynamic linking errors have occurred since the last invocation of 319.Fn dlerror , 320.Fn dlerror 321returns 322.Dv NULL . 323Thus, invoking 324.Fn dlerror 325a second time, immediately following a prior invocation, will result in 326.Dv NULL 327being returned. 328.Sh SEE ALSO 329.Xr ld 1 , 330.Xr rtld 1 , 331.Xr link 5 332.Sh HISTORY 333Some of the 334.Nm dl* 335functions first appeared in SunOS 4. 336