1.\" $NetBSD: ld.elf_so.1,v 1.4 2002/02/08 01:30:08 ross 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd October 23, 2001 38.Dt LD.ELF_SO 1 39.Os 40.Sh NAME 41.Nm ld.elf_so 42.Nd run-time link-editor (linker) 43.Sh DESCRIPTION 44.Nm 45is a self-contained, position independent program image providing run-time 46support for loading and link-editing shared objects into a process' 47address space. It uses information stored in data structures within the 48binary (see 49.Xr elf 5 ) 50and environment variables to determine which shared objects are needed. 51These shared objects are loaded at a convenient virtual address using the 52.Xr mmap 2 53system call. After all shared objects have been successfully loaded, 54.Nm 55proceeds to resolve external references from both the main program and 56all objects loaded. Once all required references are resolved control is 57passed to the program via its entry point. 58.Ss Startup 59On the execution of a dynamically linked binary the kernel will load 60the program and its run-time linker as specified in the PT_INTERP 61section in the program header. At this point, instead of passing control 62directly to the program, the kernel passes control to the specified 63linker. An auxiliary vector of information is passed that includes 64the address of the program header, the size of each entry in the header, 65and the number of entries. The entry point of the program and the base 66address of where 67.Nm 68is loaded is also supplied. 69.Pp 70Careful use of code allows 71.Nm 72to relocate itself before proceeding. Specifically the use of global 73variables and large switch statements is not allowed. The later can 74cause the output of a jump table that can use the equivalent of a 75global variable. 76.Ss Finding objects 77Each 78.Xr elf 5 79object file may contain information in its dynamic (PT_DYNAMIC) section 80about which shared objects it requires (often referred to as dependencies). 81These dependencies are specified in the optional DT_NEEDED entry within 82the dynamic section. Each DT_NEEDED entry refers to a filename string of 83the shared object that is to be searched for. 84.Pp 85The linker will search for libraries in three lists of paths: 86.Bl -enum 87.It 88A user defined list of paths as specified in LD_LIBRARY_PATH and 89.Xr ld.so.conf 5 . 90.Pp 91The use of ld.so.conf should be avoided as the setting of a global search 92path can present a security risk. 93.It 94A list of paths specified within a shared object using a DT_RPATH entry in 95the dynamic section. This is defined at shared object link time. 96.It 97The list of default paths which is set to 98.Pa /usr/lib . 99.El 100.Pp 101The filename string can be considered free form, however, it will almost 102always take the form lib\*[Lt]name\*[Gt].so.\*[Lt]number\*[Gt], where name specifies the 103.Sq library 104name and number is conceptually the library's major version number. 105.Pp 106This name and another of the form lib\*[Lt]name\*[Gt].so are normally symbolic links 107to the real shared object which has a filename of the form 108lib\*[Lt]name\*[Gt].so.\*[Lt]major\*[Gt].\*[Lt]minor\*[Gt][.\*[Lt]teeny\*[Gt]]. 109This naming convention allows a versioning scheme similar to 110.Xr a.out 5 . 111.Ss Relocation 112.Nm 113will perform all necessary relocations immediately except for relocations 114relating to the Procedure Linkage Table (PLT). The PLT is used as a 115indirection method for procedure calls to globally defined functions. It 116allows, through the use of intermediate code, the delayed binding of a call 117to a globally defined function to be performed at procedure call time. This 118.Sq lazy 119method is the default (see LD_BIND_NOW). 120.Ss Initialization 121A mechanism is provided for initialization and termination routines 122to be called, on a per-object basis before execution of the program proper 123begins or after the program has completed. This gives a shared object an 124opportunity to perform any extra set-up or completion work. 125.Pp 126The DT_INIT and DT_FINI entries in the dynamic section specify the addresses 127of the initialization and termination functions, respectively, for 128the shared object. 129.Nm 130arranges for each initialization function to be called before control is passed 131to the program and for the termination functions to be called by using 132.Xr atexit 3 . 133.Pp 134This mechanism is exploited by the system-supplied constructor 135initialization and destructor code located in 136.Pa /usr/lib/crtbeginS.o 137and 138.Pa /usr/lib/crtendS.o . 139These files are automatically included by 140.Xr cc 1 141and 142.Xr c++ 1 143in the list of object-code files passed 144to 145.Xr ld 1 146when building a shared C or C++ object. 147.Sh ENVIRONMENT 148If the following environment variables exist they will be used by 149.Nm "" . 150.Bl -tag -width "LD_LIBRARY_PATH" 151.It Ev LD_LIBRARY_PATH 152A colon separated list of directories, overriding the default search path 153for shared libraries. 154.It Ev LD_PRELOAD 155A colon or space separated list of shared object filenames to be loaded. 156Space is allowed as a separator for backwards compatibility only. Support 157may be removed in a future release and should not be relied upon. 158.Em after 159the main program but 160.Em before 161its shared object dependencies. 162.It Ev LD_BIND_NOW 163If defined immediate binding of Procedure Link Table (PLT) entries is 164performed instead of the default lazy method. 165.It Ev LD_DEBUG 166If defined a variety of debug information will be written to the standard 167error of an dynamically linked executed when it is run. 168.El 169.Sh FILES 170.Bl -tag -width /etc/ld.so.conf -compact 171.It Pa /etc/ld.so.conf 172library location hints supplied by the system administrator. 173.El 174.Sh SEE ALSO 175.Xr ld 1 , 176.Xr ld.aout_so 1 , 177.Xr dlfcn 3 , 178.Xr elf 5 179.Sh HISTORY 180The ELF shared library model employed first appeared in Sys V R4. 181.Sh SECURITY CONSIDERATIONS 182The environment variables 183.Ev LD_LIBRARY_PATH 184and 185.Ev LD_PRELOAD 186are not honored when executing in a set-user-ID or set-group-ID environment. 187This action is taken to prevent malicious substitution of shared object 188dependencies or interposition of symbols. 189