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.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 successfully loaded, 53.Nm 54proceeds to resolve external references from both the main program and 55all objects loaded. A mechanism is provided for initialization routines 56to be called, on a per-object basis, giving a shared object an opportunity 57to perform 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_IGNORE_MISSING_OBJECTS" 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_BIND_NOW 121When set to a nonempty string, causes 122.Nm 123to relocate all external function calls before starting execution of the 124program. Normally, function calls are bound lazily, at the first call 125of each function. 126.Ev LD_BIND_NOW 127increases the start-up time of a program, but it avoids run-time 128surprises caused by unexpectedly undefined functions. 129.It Ev LD_WARN_NON_PURE_CODE 130When set to a nonempty string, issue a warning whenever a link-editing 131operation requires modification of the text segment of some loaded 132object. This is usually indicative of an incorrectly built library. 133.It Ev LD_SUPPRESS_WARNINGS 134When set to a nonempty string, no warning messages of any kind are 135issued. Normally, a warning is given if satisfactorily versioned 136library could not be found. 137.It Ev LD_IGNORE_MISSING_OBJECTS 138When set to a nonempty string, makes it a nonfatal condition if 139one or more required shared objects cannot be loaded. 140Loading and execution proceeds using the objects that are 141available. 142A warning is produced for each missing object, unless the environment 143variable 144.Ev LD_SUPPRESS_WARNINGS 145is set to a nonempty string. 146.Pp 147This is ignored for set-user-ID and set-group-ID programs. 148.Pp 149Missing shared objects can be ignored without errors if all the 150following conditions hold: 151.Bl -bullet 152.It 153They do not supply definitions for any required data symbols. 154.It 155No functions defined by them are called during program execution. 156.It 157The environment variable 158.Ev LD_BIND_NOW 159is unset or is set to the empty string. 160.El 161.It Ev LD_TRACE_LOADED_OBJECTS 162When set to a nonempty string, causes 163.Nm 164to exit after loading the shared objects and printing a summary which includes 165the absolute pathnames of all objects, to standard output. 166.It Ev LD_TRACE_LOADED_OBJECTS_FMT1 167.It Ev LD_TRACE_LOADED_OBJECTS_FMT2 168When set, these variables are interpreted as format strings a la 169.Xr printf 3 170to customize the trace output and are used by 171.Xr ldd 1 's 172.Fl f 173option and allows 174.Xr ldd 1 175to be operated as a filter more conveniently. 176The following conversions can be used: 177.Bl -tag -indent "LD_TRACE_LOADED_OBJECTS_FMT1 " -width "xxxx" 178.It \&%a 179The main program's name 180.Po also known as 181.Dq __progname 182.Pc . 183.It \&%A 184The value of the environment variable 185.Ev LD_TRACE_LOADED_OBJECTS_PROGNAME 186.It \&%o 187The library name. 188.It \&%m 189The library's major version number. 190.It \&%n 191The library's minor version number. 192.It \&%p 193The full pathname as determined by 194.Nm rtld Ns 's 195library search rules. 196.It \&%x 197The library's load address. 198.El 199.Pp 200Additionally, 201.Sy \en 202and 203.Sy \et 204are recognised and have their usual meaning. 205.\" .It Ev LD_NO_INTERN_SEARCH 206.\" When set, 207.\" .Nm 208.\" does not process any internal search paths that were recorded in the 209.\" executable. 210.\" .It Ev LD_NOSTD_PATH 211.\" When set, do not include a set of built-in standard directory paths for 212.\" searching. This might be useful when running on a system with a completely 213.\" non-standard filesystem layout. 214.El 215.Pp 216.Sh FILES 217/var/run/ld.so.hints 218.Pp 219.Sh SEE ALSO 220.Xr ld 1 , 221.Xr link 5 , 222.Xr ldconfig 8 223.Sh HISTORY 224The shared library model employed first appeared in SunOS 4.0 225