1.\" $NetBSD: dlfcn.3,v 1.27 2010/01/24 22:54:14 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 January 18, 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 shared object is mapped into the address space, relocated, and 69its external references are resolved in the same way as is done 70with the implicitly loaded shared libraries at program startup. 71.Pp 72The 73.Fa path 74argument can be specified as either an absolute pathname to a shared object 75or just the name of the shared object itself. 76When an absolute pathname is specified, 77only the path provided will be searched. 78When just a shared object name is specified, the same search rules apply that are 79used for 80.Dq intrinsic 81shared object searches. 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 86If the first argument is 87.Dv NULL , 88.Fn dlopen 89returns a 90.Fa handle 91on the global symbol object. 92This object 93provides access to all symbols from an ordered set of objects consisting 94of the original program image and any dependencies loaded during startup. 95.Pp 96The 97.Fa mode 98parameter specifies symbol resolution time and symbol visibility. 99One of the following values may be used to specify symbol resolution time: 100.Bl -tag -width "RTLD_LAZYXX" -offset indent 101.It Dv RTLD_NOW 102Symbols are resolved immediately. 103.It Dv RTLD_LAZY 104Symbols are resolved when they are first referred to. 105This is the default value if resolution time is unspecified. 106.El 107.Pp 108One of the following values may be used to specify symbol visibility: 109.Pp 110.Bl -tag -width "RTLD_GLOBAL" -compact -offset indent 111.It Dv RTLD_GLOBAL 112The object's symbols and the symbols of its dependencies will be visible to 113other objects. 114.It Dv RTLD_LOCAL 115The object's symbols and the symbols of its dependencies will not be visible to 116other objects. 117This is the default value if visibility is unspecified. 118.El 119.Pp 120To specify both resolution time and visibility, bitwise inclusive OR one of 121each of the above values together. 122If an object was opened with 123.Dv RTLD_LOCAL 124and later opened with 125.Dv RTLD_GLOBAL , 126then it is promoted to 127.Dv RTLD_GLOBAL . 128.Pp 129.Fn dlopen 130returns a 131.Fa handle 132to be used in calls to 133.Fn dlclose , 134.Fn dlsym , 135and 136.Fn dlctl . 137If the named shared object has already 138been loaded by a previous call to 139.Fn dlopen 140.Pq and not yet unloaded by Fn dlclose , 141a 142.Fa handle 143referring to the resident copy is returned. 144.Pp 145.Fn dlclose 146unlinks and removes the object referred to by 147.Fa handle 148from the process address space. 149If multiple calls to 150.Fn dlopen 151have been done on this object, or the object was one loaded at startup time, 152or the object is a dependency of another object 153then the object is removed when its reference count drops to zero. 154.Fn dlclose 155returns 0 on success and non-zero on failure. 156.Pp 157.Fn dlsym 158looks for a definition of 159.Fa symbol 160in the shared object designated by 161.Fa handle , 162and all shared objects that are listed as dependencies. 163The symbol's address is returned. 164If the symbol cannot be resolved, 165.Dv NULL 166is returned. 167.Pp 168.Fn dlsym 169may also be called with special 170.Fa handle 171values. 172.Fn dlsym 173respects symbol visibility as specified by the 174.Fn dlopen 175.Fa mode 176parameter. 177However, the symbols of an object's dependencies are always visible to it. 178All shared objects loaded at program startup are globally visible. 179Only the symbols in the main executable that are referenced by a 180shared object at link time will be visible unless it has been linked 181with the --export-dynamic option where all of its symbols will be 182visible. 183The following special 184.Fa handle 185values may be used with 186.Fn dlsym : 187.Bl -tag -width "RTLD_DEFAULTXX" -offset indent 188.It Dv NULL 189Interpreted as a reference to the executable or shared object 190from which the call is being made. 191Thus an object can reference its own symbols and the symbols of its 192dependencies without calling 193.Fn dlopen . 194.It Dv RTLD_DEFAULT 195All the visible shared objects and the executable will be searched in the order they 196were loaded. 197.It Dv RTLD_NEXT 198The search for 199.Fa symbol 200is limited to the visible shared objects which were loaded after the one issuing the 201call to 202.Fn dlsym . 203Thus, if 204.Fn dlsym 205is called from the main program, all the visible shared libraries are searched. 206If it is called from a shared library, all subsequently visible shared 207libraries are searched. 208.It Dv RTLD_SELF 209The search for 210.Fa symbol 211is limited to the shared object issuing the call to 212.Fn dlsym 213and those shared objects which were loaded after it that are visible. 214.El 215.Pp 216.Fn dladdr 217examines all currently mapped shared objects for a symbol whose address -- 218as mapped in the process address space -- is closest to but not exceeding 219the value passed in the first argument 220.Fa addr . 221The symbols of a shared object are only eligible if 222.Va addr 223is between the base address of the shared object and the value of the 224symbol 225.Dq _end 226in the same shared object. 227If no object for which this condition holds 228true can be found, 229.Fn dladdr 230will return 0. 231Otherwise, a non-zero value is returned and the 232.Fa dli 233argument will be used to provide information on the selected symbol 234and the shared object it is contained in. 235The 236.Fa dli 237argument points at a caller-provided 238.Va Dl_info 239structure defined as follows: 240.Bd -literal -offset indent 241typedef struct { 242 const char *dli_fname; /* File defining the symbol */ 243 void *dli_fbase; /* Base address */ 244 const char *dli_sname; /* Symbol name */ 245 const void *dli_saddr; /* Symbol address */ 246} Dl_info; 247.Ed 248.Pp 249The structure members are further described as follows: 250.Bl -tag -width "dli_fnameXX" 251.It Li "dli_fname" 252The pathname of the shared object containing the address 253.Fa addr . 254.It Li "dli_fbase" 255The base address at which this shared object is loaded in the process 256address space. 257This may be zero if the symbol was found in the internally generated 258.Dq copy 259section 260.Po 261see 262.Xr link 5 263.Pc 264which is not associated with a file. 265.It Li "dli_sname" 266points at the nul-terminated name of the selected symbol 267.It Li "dli_saddr" 268is the actual address 269.Pq as it appears in the process address space 270of the symbol. 271.El 272.Pp 273Note: both strings pointed at by 274.Va dli_fname 275and 276.Va dli_sname 277reside in memory private to the run-time linker module and should not 278be modified by the caller. 279.Pp 280In dynamically linked programs, the address of a global function will 281point to its program linkage table entry, rather than to the entry 282point of the function itself. 283This causes most global functions to appear to be defined within the 284main executable, rather than in the shared libraries where the actual 285code resides. 286.Pp 287.Fn dlctl 288provides an interface similar to 289.Xr ioctl 2 290to control several aspects of the run-time linker's operation. 291This interface is 292.Ud 293.Pp 294.Fn dlerror 295returns a character string representing the most recent error that has 296occurred while processing one of the other functions described here. 297If no dynamic linking errors have occurred since the last invocation of 298.Fn dlerror , 299.Fn dlerror 300returns 301.Dv NULL . 302Thus, invoking 303.Fn dlerror 304a second time, immediately following a prior invocation, will result in 305.Dv NULL 306being returned. 307.Sh SEE ALSO 308.Xr ld 1 , 309.Xr rtld 1 , 310.Xr link 5 311.Sh HISTORY 312Some of the 313.Nm dl* 314functions first appeared in SunOS 4. 315