1.\" $NetBSD: ld.elf_so.1,v 1.12 2008/05/25 19:48:35 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 May 18, 2007 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.Pp 66Careful use of code allows 67.Nm 68to relocate itself before proceeding. 69Specifically the use of global variables and 70large switch statements is not allowed. 71The later can cause the output of a jump table that 72can use the equivalent of a global variable. 73.Ss Finding objects 74Each 75.Xr elf 5 76object file may contain information in its dynamic (PT_DYNAMIC) section 77about which shared objects it requires (often referred to as dependencies). 78These dependencies are specified in the optional DT_NEEDED entry within 79the dynamic section. 80Each DT_NEEDED entry refers to a filename string of 81the shared object that is to be searched for. 82.Pp 83The linker will search for libraries in three lists of paths: 84.Bl -enum 85.It 86A user defined list of paths as specified in LD_LIBRARY_PATH and 87.Xr ld.so.conf 5 . 88.Pp 89The use of ld.so.conf should be avoided as the setting of a global search 90path can present a security risk. 91.It 92A list of paths specified within a shared object using a DT_RPATH entry in 93the dynamic section. 94This is defined at shared object link time. 95.It 96The list of default paths which is set to 97.Pa /usr/lib . 98.El 99.Pp 100.Nm 101will expand the following variables if present in the paths: 102.Bl -tag -width $PLATFORM 103.It $HWCAP 104Processor hardware capabilities, for example FPU, MMX, SSE. 105Currently unimplemented. 106.It $ISALIST 107List of instructions sets this processor can execute. 108Currently unimplemented. 109.It $ORIGIN 110The directory of the main object. 111.It $OSNAME 112The value of the 113.Dv kern.ostype 114.Xr sysctl 3 . 115.It $OSREL 116The value of the 117.Dv kern.osrelease 118.Xr sysctl 3 . 119.It $PLATFORM 120The value of the 121.Dv hw.machine_arch 122.Xr sysctl 3 . 123.El 124.Pp 125Both 126.Dv ${VARIABLE} 127and 128.Dv $VARIABLE 129are recognized. 130.Pp 131The filename string can be considered free form, however, it will almost 132always take the form lib\*[Lt]name\*[Gt].so.\*[Lt]number\*[Gt], 133where name specifies the 134.Sq library 135name and number is conceptually the library's major version number. 136.Pp 137This name and another of the form lib\*[Lt]name\*[Gt].so are normally 138symbolic links to the real shared object which has a filename of the form 139lib\*[Lt]name\*[Gt].so.\*[Lt]major\*[Gt].\*[Lt]minor\*[Gt][.\*[Lt]teeny\*[Gt]]. 140This naming convention allows a versioning scheme similar to 141.Xr a.out 5 . 142.Ss Relocation 143.Nm 144will perform all necessary relocations immediately except for relocations 145relating to the Procedure Linkage Table (PLT). 146The PLT is used as a indirection method for procedure 147calls to globally defined functions. 148It allows, through the use of intermediate code, the delayed binding of 149a call to a globally defined function to be performed at procedure call time. 150This 151.Sq lazy 152method is the default (see LD_BIND_NOW). 153.Ss Initialization 154A mechanism is provided for initialization and termination routines 155to be called, on a per-object basis before execution of the program proper 156begins or after the program has completed. 157This gives a shared object an opportunity to perform 158any extra set-up or completion work. 159.Pp 160The DT_INIT and DT_FINI entries in the dynamic section specify the addresses 161of the initialization and termination functions, respectively, for 162the shared object. 163.Nm 164arranges for each initialization function to be called before control is passed 165to the program and for the termination functions to be called by using 166.Xr atexit 3 . 167.Pp 168This mechanism is exploited by the system-supplied constructor 169initialization and destructor code located in 170.Pa /usr/lib/crtbeginS.o 171and 172.Pa /usr/lib/crtendS.o . 173These files are automatically included by 174.Xr cc 1 175and 176.Xr c++ 1 177in the list of object-code files passed to 178.Xr ld 1 179when building a shared C or C++ object. 180.Sh ENVIRONMENT 181If the following environment variables exist they will be used by 182.Nm . 183.Bl -tag -width "LD_LIBRARY_PATH" 184.It Ev LD_LIBRARY_PATH 185A colon separated list of directories, overriding the default search path 186for shared libraries. 187.It Ev LD_PRELOAD 188A colon or space separated list of shared object filenames to be loaded 189.Em after 190the main program but 191.Em before 192its shared object dependencies. 193Space is allowed as a separator for backwards compatibility only. 194Support may be removed in a future release and should not be relied upon. 195.It Ev LD_BIND_NOW 196If defined immediate binding of Procedure Link Table (PLT) entries is 197performed instead of the default lazy method. 198.It Ev LD_DEBUG 199If defined a variety of debug information will be written to the standard 200error of an dynamically linked executed when it is run. 201This variable is only recognized if 202.Nm 203was compiled with debugging support 204.Sy ( -DDEBUG ) . 205.El 206.Sh FILES 207.Bl -tag -width /etc/ld.so.conf -compact 208.It Pa /etc/ld.so.conf 209library location hints supplied by the system administrator. 210.El 211.Sh SEE ALSO 212.Xr ld 1 , 213.Xr ld.aout_so 1 , 214.Xr dlfcn 3 , 215.Xr elf 5 216.Sh HISTORY 217The ELF shared library model employed first appeared in Sys V R4. 218.Pp 219The path expansion variables first appeared in Solaris 10, and 220in 221.Nx 5.0 . 222.Sh SECURITY CONSIDERATIONS 223The environment variables 224.Ev LD_LIBRARY_PATH 225and 226.Ev LD_PRELOAD 227are not honored when executing in a set-user-ID or set-group-ID environment. 228This action is taken to prevent malicious substitution of shared object 229dependencies or interposition of symbols. 230