1.\" $NetBSD: ld.aout_so.1,v 1.8 2008/04/30 13:10:52 martin 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 March 24, 2000 31.Dt LD.AOUT_SO 1 32.Os 33.Sh NAME 34.Nm ld.so 35.Nd run-time link-editor 36.Sh DESCRIPTION 37.Nm 38is a self-contained, position independent program image 39providing run-time support for loading and link-editing 40shared objects into a process' address space. 41It uses the data structures 42.Po 43see 44.Xr link 5 45.Pc 46contained within dynamically linked programs to determine which shared 47libraries are needed and loads them at a convenient virtual address 48using the 49.Xr mmap 2 50system call. 51.Pp 52After all shared libraries have been successfully loaded, 53.Nm 54proceeds to resolve external references from both the main program and 55all objects loaded. 56A mechanism is provided for initialization routines to be called, 57on a per-object basis, giving a shared object an opportunity 58to perform any extra set-up, before execution of the program proper begins. 59.Nm 60looks for a symbol named 61.Em .init 62in each object's symbol table. 63If present, this symbol is assumed to represent a C-function declared as 64.Ft void 65.Fn .init "void" , 66which is then called. 67Similarly, a 68.Ft void 69.Fn .fini "void" 70function is called just before an object is unloaded from the process 71address space as a result of calling 72.Xr dlclose 3 . 73Note that while an object's 74.Em .init 75is always called, whether the object is loaded automatically at program 76startup or programmatically by using 77.Xr dlopen 3 , 78the 79.Em .fini 80function is called only on 81.Sq last Xr dlclose 3 . 82.Pp 83This mechanism is exploited by the system-supplied C++ constructor 84initialization code located in 85.Pa /usr/lib/c++rt.o . 86This file should be included in the list of object-code files passed to 87.Xr ld 1 88when building a shared C++ library. 89.Pp 90.Nm 91is itself a shared object that is initially loaded by the startup module 92.Em crt0 . 93Since 94.Xr a.out 5 95formats do not provide easy access to the file header from within a running 96process, 97.Em crt0 98uses the special symbol 99.Va _DYNAMIC 100to determine whether a program is in fact dynamically linked or not. 101Whenever the linker 102.Xr ld 1 103has relocated this symbol to a location other than 0, 104.Em crt0 105assumes the services of 106.Nm 107are needed 108.Po 109see 110.Xr link 5 111for details 112.Pc . 113.Em crt0 114passes control to 115.Nm rtld Ns 's 116entry point before the program's 117.Fn main 118routine is called. 119Thus, 120.Nm 121can complete the link-editing process before the dynamic program calls upon 122services of any dynamic library. 123.Pp 124To quickly locate the required shared objects in the filesystem, 125.Nm 126may use a 127.Dq hints 128file, prepared by the 129.Xr ldconfig 8 130utility, in which the full path specification of the shared objects can be 131looked up by hashing on the 3-tuple 132.Ao 133library-name, major-version-number, minor-version-number 134.Ac Ns \&. 135.Pp 136.Nm 137recognizes a number of environment variables that can be used to modify 138its behavior as follows: 139.Pp 140.Bl -tag -width LD_TRACE_LOADED_OBJECTS \" intentionally not the longest 141.It Ev LD_LIBRARY_PATH 142A colon separated list of directories, overriding the default search path 143for shared libraries. 144.It Ev LD_PRELOAD 145A colon separated list of shared object filenames to be loaded 146.Em after 147the main program but 148.Em before 149its shared object dependencies. 150.It Ev LD_WARN_NON_PURE_CODE 151When set, issue a warning whenever a link-editing operation requires 152modification of the text segment of some loaded object. 153This is usually indicative of an incorrectly built library. 154.It Ev LD_SUPPRESS_WARNINGS 155When set, no warning messages of any kind are issued. 156Normally, a warning is given if satisfactorily versioned 157library could not be found. 158.It Ev LD_TRACE_LOADED_OBJECTS 159When set, causes 160.Nm 161to exit after loading the shared objects and printing a summary which includes 162the absolute pathnames of all objects, to standard output. 163.It Ev LD_TRACE_LOADED_OBJECTS_FMT1 164.It Ev LD_TRACE_LOADED_OBJECTS_FMT2 165When set, these variables are interpreted as format strings a la 166.Xr printf 3 167to customize the trace output and are used by 168.Xr ldd 1 Ns 's 169.Fl f 170option and allows 171.Xr ldd 1 172to be operated as a filter more conveniently. 173The following conversions can be used: 174.Bl -tag -width xxxx 175.It \&%a 176The main program's name 177.Po also known as 178.Dq __progname 179.Pc . 180.It \&%A 181The value of the environment variable 182.Ev LD_TRACE_LOADED_OBJECTS_PROGNAME 183.It \&%o 184The library name. 185.It \&%m 186The library's major version number. 187.It \&%n 188The library's minor version number. 189.It \&%p 190The full pathname as determined by 191.Nm rtld Ns 's 192library search rules. 193.It \&%x 194The library's load address. 195.El 196.Pp 197Additionally, 198.Sy \en 199and 200.Sy \et 201are recognized and have their usual meaning. 202.It Ev LD_NO_INTERN_SEARCH 203When set, 204.Nm 205does not process any internal search paths that were recorded in the 206executable. 207.It Ev LD_NOSTD_PATH 208When set, do not include a set of built-in standard directory paths for 209searching. 210This might be useful when running on a system with a completely 211non-standard filesystem layout. 212.El 213.Sh FILES 214.Bl -tag -width /var/run/ld.so.hintsXXX -compact 215.It Pa /var/run/ld.so.hints 216library location hints built by 217.Xr ldconfig 8 218.El 219.Sh SEE ALSO 220.Xr ld 1 , 221.Xr ld.elf_so 1 , 222.Xr ld.so 1 , 223.Xr link 5 , 224.Xr ldconfig 8 225.Sh HISTORY 226The shared library model employed first appeared in SunOS 4.0. 227.Sh SECURITY CONSIDERATIONS 228The environment variables 229.Ev LD_LIBRARY_PATH 230and 231.Ev LD_PRELOAD 232are not honored when executing in a set-user-ID or set-group-ID environment. 233This action is taken to prevent malicious substitution of shared object 234dependencies or interposition of symbols. 235