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