1.\" $FreeBSD$ 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 acknowledgment: 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.Nm rtld 37.Nd run-time link-editor 38.Sh DESCRIPTION 39.Nm 40is a self-contained, position independent program image providing run-time 41support for loading and link-editing shared objects into a process' 42address space. It uses the data structures 43.Po 44see 45.Xr link 5 46.Pc 47contained within dynamically linked programs to determine which shared 48libraries are needed and loads them at a convenient virtual address 49using the 50.Xr mmap 2 51system call. 52.Pp 53After all shared libraries have been successfully loaded, 54.Nm 55proceeds to resolve external references from both the main program and 56all objects loaded. A mechanism is provided for initialization routines 57to be called, on a per-object basis, giving a shared object an opportunity 58to perform any extra set-up, before execution of the program proper begins. 59This is useful for C++ libraries that contain static constructors. 60.Pp 61.Nm 62is itself a shared object that is initially loaded by the startup module 63.Em crt0 . 64Since 65.Xr a.out 5 66formats do not provide easy access to the file header from within a running 67process, 68.Em crt0 69uses the special symbol 70.Va _DYNAMIC 71to determine whether a program is in fact dynamically linked or not. Whenever 72the linker 73.Xr ld 1 74has relocated this symbol to a location other than 0, 75.Em crt0 76assumes the services of 77.Nm 78are needed 79.Po 80see 81.Xr link 5 82for details 83.Pc \&. 84.Em crt0 85passes control to 86.Nm 87\&'s entry point before the program's 88.Fn main 89routine is called. Thus, 90.Nm 91can complete the link-editing process before the dynamic program calls upon 92services of any dynamic library. 93.Pp 94To quickly locate the required shared objects in the filesystem, 95.Nm 96may use a 97.Dq hints 98file, prepared by the 99.Xr ldconfig 8 100utility, in which the full path specification of the shared objects can be 101looked up by hashing on the 3-tuple 102.Ao 103library-name, major-version-number, minor-version-number 104.Ac \&. 105.Pp 106.Nm 107recognizes a number of environment variables that can be used to modify 108its behaviour as follows: 109.Pp 110.Bl -tag -width "LD_IGNORE_MISSING_OBJECTS" 111.It Ev LD_LIBRARY_PATH 112A colon separated list of directories, overriding the default search path 113for shared libraries. 114This is ignored for set-user-ID and set-group-ID programs. 115.It Ev LD_PRELOAD 116A colon separated list of shared libraries, to be linked in before any 117other shared libraries. If the directory is not specified then 118the directories specified by LD_LIBRARY_PATH will be searched first 119followed by the set of built-in standard directories. 120This is ignored for set-user-ID and set-group-ID programs. 121.It Ev LD_BIND_NOW 122When set to a nonempty string, causes 123.Nm 124to relocate all external function calls before starting execution of the 125program. Normally, function calls are bound lazily, at the first call 126of each function. 127.Ev LD_BIND_NOW 128increases the start-up time of a program, but it avoids run-time 129surprises caused by unexpectedly undefined functions. 130.It Ev LD_WARN_NON_PURE_CODE 131When set to a nonempty string, issue a warning whenever a link-editing 132operation requires modification of the text segment of some loaded 133object. This is usually indicative of an incorrectly built library. 134.It Ev LD_SUPPRESS_WARNINGS 135When set to a nonempty string, no warning messages of any kind are 136issued. Normally, a warning is given if satisfactorily versioned 137library could not be found. 138.It Ev LD_IGNORE_MISSING_OBJECTS 139When set to a nonempty string, makes it a nonfatal condition if 140one or more required shared objects cannot be loaded. 141Loading and execution proceeds using the objects that are 142available. 143A warning is produced for each missing object, unless the environment 144variable 145.Ev LD_SUPPRESS_WARNINGS 146is set to a nonempty string. 147.Pp 148This is ignored for set-user-ID and set-group-ID programs. 149.Pp 150Missing shared objects can be ignored without errors if all the 151following conditions hold: 152.Bl -bullet 153.It 154They do not supply definitions for any required data symbols. 155.It 156No functions defined by them are called during program execution. 157.It 158The environment variable 159.Ev LD_BIND_NOW 160is unset or is set to the empty string. 161.El 162.It Ev LD_TRACE_LOADED_OBJECTS 163When set to a nonempty string, causes 164.Nm 165to exit after loading the shared objects and printing a summary which includes 166the absolute pathnames of all objects, to standard output. 167.It Ev LD_TRACE_LOADED_OBJECTS_FMT1 168.It Ev LD_TRACE_LOADED_OBJECTS_FMT2 169When set, these variables are interpreted as format strings a la 170.Xr printf 3 171to customize the trace output and are used by 172.Xr ldd 1 's 173.Fl f 174option and allows 175.Xr ldd 1 176to be operated as a filter more conveniently. 177The following conversions can be used: 178.Bl -tag -indent "LD_TRACE_LOADED_OBJECTS_FMT1 " -width "xxxx" 179.It \&%a 180The main program's name 181.Po also known as 182.Dq __progname 183.Pc . 184.It \&%A 185The value of the environment variable 186.Ev LD_TRACE_LOADED_OBJECTS_PROGNAME 187.It \&%o 188The library name. 189.It \&%m 190The library's major version number. 191.It \&%n 192The library's minor version number. 193.It \&%p 194The full pathname as determined by 195.Nm rtld Ns 's 196library search rules. 197.It \&%x 198The library's load address. 199.El 200.Pp 201Additionally, 202.Sy \en 203and 204.Sy \et 205are recognized and have their usual meaning. 206.\" .It Ev LD_NO_INTERN_SEARCH 207.\" When set, 208.\" .Nm 209.\" does not process any internal search paths that were recorded in the 210.\" executable. 211.\" .It Ev LD_NOSTD_PATH 212.\" When set, do not include a set of built-in standard directory paths for 213.\" searching. This might be useful when running on a system with a completely 214.\" non-standard filesystem layout. 215.El 216.Pp 217.Sh FILES 218/var/run/ld.so.hints 219.Pp 220.Sh SEE ALSO 221.Xr ld 1 , 222.Xr link 5 , 223.Xr ldconfig 8 224.Sh HISTORY 225The shared library model employed first appeared in SunOS 4.0 226