1.\" $Id$ 2.\" 3.\" Copyright (c) 1995 Paul Kranenburg 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by Paul Kranenburg. 17.\" 3. The name of the author may not be used to endorse or promote products 18.\" derived from this software without specific prior written permission 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 21.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 22.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 23.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 25.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 29.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd June 27, 1995 32.Dt RTLD 1 33.Os FreeBSD 34.Sh NAME 35.Nm ld.so 36.Nd run-time link-editor 37.Sh DESCRIPTION 38.Nm 39is a self-contained, position independent program image providing run-time 40support for loading and link-editing shared objects into a process' 41address space. It 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 succesfully loaded, 53.Nm 54proceeds to resolve external references from both the main program and 55all objects loaded. A mechanism is provided for initialisation routines 56to be called, on a per-object basis, giving a shared object an opportunity 57to perfrom any extra set-up, before execution of the program proper begins. 58This is useful for C++ libraries that contain static constrictors. 59.Pp 60.Nm 61is itself a shared object that is initially loaded by the startup module 62.Em crt0 . 63Since 64.Xr a.out 5 65formats do not provide easy access to the file header from within a running 66process, 67.Em crt0 68uses the special symbol 69.Va _DYNAMIC 70to determine whether a program is in fact dynamically linked or not. Whenever 71the linker 72.Xr ld 1 73has relocated this symbol to a location other then 0, 74.Em crt0 75assumes the services of 76.Nm 77are needed 78.Po 79see 80.Xr link 5 81for details 82.Pc \&. 83.Em crt0 84passes control to 85.Nm 86\&'s entry point before the program's 87.Fn main 88routine is called. Thus, 89.Nm 90can complete the link-editing process before the dynamic program calls upon 91services of any dynamic library. 92.Pp 93To quickly locate the required shared objects in the filesystem, 94.Nm 95may use a 96.Dq hints 97file, prepared by the 98.Xr ldconfig 8 99utility, in which the full path specification of the shared objects can be 100looked up by hashing on the 3-tuple 101.Ao 102library-name, major-version-number, minor-version-number 103.Ac \&. 104.Pp 105.Nm 106recognises a number of environment variables that can be used to modify 107its behaviour as follows: 108.Pp 109.Bl -tag -width "LD_TRACE_LOADED_OBJECTS" 110.It Ev LD_LIBRARY_PATH 111A colon separated list of directories, overriding the default search path 112for shared libraries. 113.It Ev LD_WARN_NON_PURE_CODE 114When set, issue a warning whenever a link-editing operation requires 115modification of the text segment of some loaded object. This is usually 116indicative of an incorrectly built library. 117.It Ev LD_SUPPRESS_WARNINGS 118When set, no warning messages of any kind are issued. Normally, a warning 119is given if satisfactorily versioned library could not be found. 120.It Ev LD_TRACE_LOADED_OBJECTS 121When set, causes 122.Nm 123to exit after loading the shared objects and printing a summary which includes 124the absolute pathnames of all objects, to standard output. 125.It Ev LD_NO_INTERN_SEARCH 126When set, 127.Nm 128does not process any internal search paths that were recorded in the 129executable. 130.It Ev LD_NOSTD_PATH 131When set, do not include a set of built-in standard directory paths for 132searching. This might be useful when running on a system with a completely 133non-standard filesystem layout. 134.El 135.Pp 136.Sh FILES 137/var/run/ld.so.hints 138.Pp 139.Sh SEE ALSO 140.Xr ld 1 141.Xr ldconfig 8 142.Xr link 5 143.Sh HISTORY 144The shared library model employed first appeared in SunOS 4.0 145