1.\" $Id: rtld.1,v 1.4 1996/09/23 22:22:03 wosch Exp $ 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_PROGNAME" 110.It Ev LD_LIBRARY_PATH 111A colon separated list of directories, overriding the default search path 112for shared libraries. 113This is ignored for set-user-ID and set-group-ID programs. 114.It Ev LD_PRELOAD 115A colon separated list of shared libraries, to be linked in before any 116other shared libraries. If the directory is not specified then 117the directories specified by LD_LIBRARY_PATH will be searched first 118followed by the set of built-in standard directories. 119This is ignored for set-user-ID and set-group-ID programs. 120.It Ev LD_WARN_NON_PURE_CODE 121When set, issue a warning whenever a link-editing operation requires 122modification of the text segment of some loaded object. This is usually 123indicative of an incorrectly built library. 124.It Ev LD_SUPPRESS_WARNINGS 125When set, no warning messages of any kind are issued. Normally, a warning 126is given if satisfactorily versioned library could not be found. 127.It Ev LD_TRACE_LOADED_OBJECTS 128When set, causes 129.Nm 130to exit after loading the shared objects and printing a summary which includes 131the absolute pathnames of all objects, to standard output. 132.It Ev LD_TRACE_LOADED_OBJECTS_FMT1 133.It Ev LD_TRACE_LOADED_OBJECTS_FMT2 134When set, these variables are interpreted as format strings a la 135.Xr printf 3 136to customize the trace output and are used by 137.Xr ldd 1 's 138.Fl f 139option and allows 140.Xr ldd 1 141to be operated as a filter more conveniently. 142The following conversions can be used: 143.Bl -tag -indent "LD_TRACE_LOADED_OBJECTS_FMT1 " -width "xxxx" 144.It \&%a 145The main program's name 146.Po also known as 147.Dq __progname 148.Pc . 149.It \&%A 150The value of the environment variable 151.Ev LD_TRACE_LOADED_OBJECTS_PROGNAME 152.It \&%o 153The libary name. 154.It \&%m 155The library's major version numer. 156.It \&%n 157The library's minor version numer. 158.It \&%p 159The full pathname as determined by 160.Nm rtld Ns 's 161library search rules. 162.It \&%x 163The library's load address. 164.El 165.Pp 166Additionally, 167.Sy \en 168and 169.Sy \et 170are recognised and have their usual meaning. 171.\" .It Ev LD_NO_INTERN_SEARCH 172.\" When set, 173.\" .Nm 174.\" does not process any internal search paths that were recorded in the 175.\" executable. 176.\" .It Ev LD_NOSTD_PATH 177.\" When set, do not include a set of built-in standard directory paths for 178.\" searching. This might be useful when running on a system with a completely 179.\" non-standard filesystem layout. 180.El 181.Pp 182.Sh FILES 183/var/run/ld.so.hints 184.Pp 185.Sh SEE ALSO 186.Xr ld 1 , 187.Xr ldconfig 8 , 188.Xr link 5 189.Sh HISTORY 190The shared library model employed first appeared in SunOS 4.0 191