1.\" $NetBSD: ld.aout_so.1,v 1.10 2011/01/01 16:34:52 plunky 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 January 1, 2011 31.Dt LD.AOUT_SO 1 32.Os 33.Sh NAME 34.Nm ld.aout_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.\" intentionally not the longest 141.Bl -tag -width LD_TRACE_LOADED_OBJECTS 142.It Ev LD_LIBRARY_PATH 143A colon separated list of directories, overriding the default search path 144for shared libraries. 145.It Ev LD_PRELOAD 146A colon separated list of shared object filenames to be loaded 147.Em after 148the main program but 149.Em before 150its shared object dependencies. 151.It Ev LD_WARN_NON_PURE_CODE 152When set, issue a warning whenever a link-editing operation requires 153modification of the text segment of some loaded object. 154This is usually indicative of an incorrectly built library. 155.It Ev LD_SUPPRESS_WARNINGS 156When set, no warning messages of any kind are issued. 157Normally, a warning is given if satisfactorily versioned 158library could not be found. 159.It Ev LD_TRACE_LOADED_OBJECTS 160When set, causes 161.Nm 162to exit after loading the shared objects and printing a summary which includes 163the absolute pathnames of all objects, to standard output. 164.It Ev LD_TRACE_LOADED_OBJECTS_FMT1 165.It Ev LD_TRACE_LOADED_OBJECTS_FMT2 166When set, these variables are interpreted as format strings a la 167.Xr printf 3 168to customize the trace output and are used by 169.Xr ldd 1 Ns 's 170.Fl f 171option and allows 172.Xr ldd 1 173to be operated as a filter more conveniently. 174The following conversions can be used: 175.Bl -tag -width xxxx 176.It \&%a 177The main program's name 178.Po also known as 179.Dq __progname 180.Pc . 181.It \&%A 182The value of the environment variable 183.Ev LD_TRACE_LOADED_OBJECTS_PROGNAME 184.It \&%o 185The library name. 186.It \&%m 187The library's major version number. 188.It \&%n 189The library's minor version number. 190.It \&%p 191The full pathname as determined by 192.Nm rtld Ns 's 193library search rules. 194.It \&%x 195The library's load address. 196.El 197.Pp 198Additionally, 199.Sy \en 200and 201.Sy \et 202are recognized and have their usual meaning. 203.It Ev LD_NO_INTERN_SEARCH 204When set, 205.Nm 206does not process any internal search paths that were recorded in the 207executable. 208.It Ev LD_NOSTD_PATH 209When set, do not include a set of built-in standard directory paths for 210searching. 211This might be useful when running on a system with a completely 212non-standard filesystem layout. 213.El 214.Sh FILES 215.Bl -tag -width /var/run/ld.so.hintsXXX -compact 216.It Pa /var/run/ld.so.hints 217library location hints built by 218.Xr ldconfig 8 219.El 220.Sh SEE ALSO 221.Xr ld 1 , 222.Xr ld.elf_so 1 , 223.Xr ld.so 1 , 224.Xr link 5 , 225.Xr ldconfig 8 226.Sh HISTORY 227The shared library model employed first appeared in SunOS 4.0. 228.Sh SECURITY CONSIDERATIONS 229The environment variables 230.Ev LD_LIBRARY_PATH 231and 232.Ev LD_PRELOAD 233are not honored when executing in a set-user-ID or set-group-ID environment. 234This action is taken to prevent malicious substitution of shared object 235dependencies or interposition of symbols. 236