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