1.\" $NetBSD: ld.elf_so.1,v 1.15 2010/12/17 08:50:26 wiz Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Nick Hudson. 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 17, 2010 31.Dt LD.ELF_SO 1 32.Os 33.Sh NAME 34.Nm ld.elf_so 35.Nd run-time link-editor (linker) 36.Sh DESCRIPTION 37.Nm 38is a self-contained, position independent program 39image providing run-time support for loading and 40link-editing shared objects into a process' address space. 41It uses information stored in data structures within the binary (see 42.Xr elf 5 ) 43and environment variables to determine which shared objects are needed. 44These shared objects are loaded at a convenient virtual address using the 45.Xr mmap 2 46system call. 47After all shared objects have been successfully loaded, 48.Nm 49proceeds to resolve external references from both 50the main program and all objects loaded. 51Once all required references are resolved control is 52passed to the program via its entry point. 53.Ss Startup 54On the execution of a dynamically linked binary the kernel will load 55the program and its run-time linker as specified in the PT_INTERP 56section in the program header. 57At this point, instead of passing control directly to the program, 58the kernel passes control to the specified linker. 59An auxiliary vector of information is passed that includes 60the address of the program header, the size of each entry in the header, 61and the number of entries. 62The entry point of the program and the base address of where 63.Nm 64is loaded is also supplied. 65.Ss Finding objects 66Each 67.Xr elf 5 68object file may contain information in its dynamic (PT_DYNAMIC) section 69about which shared objects it requires (often referred to as dependencies). 70These dependencies are specified in the optional DT_NEEDED entry within 71the dynamic section. 72Each DT_NEEDED entry refers to a filename string of 73the shared object that is to be searched for. 74.Pp 75The linker will search for libraries in three lists of paths: 76.Bl -enum 77.It 78A user defined list of paths as specified in LD_LIBRARY_PATH and 79.Xr ld.so.conf 5 . 80.Pp 81The use of ld.so.conf should be avoided as the setting of a global search 82path can present a security risk. 83.It 84A list of paths specified within a shared object using a DT_RPATH entry in 85the dynamic section. 86This is defined at shared object link time. 87.It 88The list of default paths which is set to 89.Pa /usr/lib . 90.El 91.Pp 92.Nm 93will expand the following variables if present in the paths: 94.Bl -tag -width $PLATFORM 95.It $HWCAP 96Processor hardware capabilities, for example FPU, MMX, SSE. 97Currently unimplemented. 98.It $ISALIST 99List of instructions sets this processor can execute. 100Currently unimplemented. 101.It $ORIGIN 102The directory of the main object. 103Implemented in 104.Nm 105but the kernel support is currently disabled. 106.It $OSNAME 107The value of the 108.Dv kern.ostype 109.Xr sysctl 3 . 110.It $OSREL 111The value of the 112.Dv kern.osrelease 113.Xr sysctl 3 . 114.It $PLATFORM 115The value of the 116.Dv hw.machine_arch 117.Xr sysctl 3 . 118.El 119.Pp 120Both 121.Dv ${VARIABLE} 122and 123.Dv $VARIABLE 124are recognized. 125.Pp 126The filename string can be considered free form, however, it will almost 127always take the form lib\*[Lt]name\*[Gt].so.\*[Lt]number\*[Gt], 128where name specifies the 129.Sq library 130name and number is conceptually the library's major version number. 131.Pp 132This name and another of the form lib\*[Lt]name\*[Gt].so are normally 133symbolic links to the real shared object which has a filename of the form 134lib\*[Lt]name\*[Gt].so.\*[Lt]major\*[Gt].\*[Lt]minor\*[Gt][.\*[Lt]teeny\*[Gt]]. 135This naming convention allows a versioning scheme similar to 136.Xr a.out 5 . 137.Ss Relocation 138.Nm 139will perform all necessary relocations immediately except for relocations 140relating to the Procedure Linkage Table (PLT). 141The PLT is used as a indirection method for procedure 142calls to globally defined functions. 143It allows, through the use of intermediate code, the delayed binding of 144a call to a globally defined function to be performed at procedure call time. 145This 146.Sq lazy 147method is the default (see LD_BIND_NOW). 148.Ss Initialization 149A mechanism is provided for initialization and termination routines 150to be called, on a per-object basis before execution of the program proper 151begins or after the program has completed. 152This gives a shared object an opportunity to perform 153any extra set-up or completion work. 154.Pp 155The DT_INIT and DT_FINI entries in the dynamic section specify the addresses 156of the initialization and termination functions, respectively, for 157the shared object. 158.Nm 159arranges for each initialization function to be called before control is passed 160to the program and for the termination functions to be called by using 161.Xr atexit 3 . 162.Pp 163This mechanism is exploited by the system-supplied constructor 164initialization and destructor code located in 165.Pa /usr/lib/crtbeginS.o 166and 167.Pa /usr/lib/crtendS.o . 168These files are automatically included by 169.Xr cc 1 170and 171.Xr c++ 1 172in the list of object-code files passed to 173.Xr ld 1 174when building a shared C or C++ object. 175.Sh ENVIRONMENT 176If the following environment variables exist they will be used by 177.Nm . 178.Bl -tag -width "LD_LIBRARY_PATH" 179.It Ev LD_LIBRARY_PATH 180A colon separated list of directories, overriding the default search path 181for shared libraries. 182.It Ev LD_PRELOAD 183A colon or space separated list of shared object filenames to be loaded 184.Em after 185the main program but 186.Em before 187its shared object dependencies. 188Space is allowed as a separator for backwards compatibility only. 189Support may be removed in a future release and should not be relied upon. 190.It Ev LD_BIND_NOW 191If defined immediate binding of Procedure Link Table (PLT) entries is 192performed instead of the default lazy method. 193.It Ev LD_DEBUG 194If defined a variety of debug information will be written to the standard 195error of an dynamically linked executed when it is run. 196This variable is only recognized if 197.Nm 198was compiled with debugging support 199.Sy ( -DDEBUG ) . 200.El 201.Sh FILES 202.Bl -tag -width /etc/ld.so.conf -compact 203.It Pa /etc/ld.so.conf 204library location hints supplied by the system administrator. 205.El 206.Sh SEE ALSO 207.Xr ld 1 , 208.Xr ld.aout_so 1 , 209.Xr dlfcn 3 , 210.Xr elf 5 211.Sh HISTORY 212The ELF shared library model employed first appeared in Sys V R4. 213.Pp 214The path expansion variables first appeared in Solaris 10, and 215in 216.Nx 5.0 . 217.Sh SECURITY CONSIDERATIONS 218The environment variables 219.Ev LD_LIBRARY_PATH 220and 221.Ev LD_PRELOAD 222are not honored when executing in a set-user-ID or set-group-ID environment. 223This action is taken to prevent malicious substitution of shared object 224dependencies or interposition of symbols. 225