From 53060be2a3eb2319dad9d72c30fc1004a7af8c6c Mon Sep 17 00:00:00 2001 From: jdp Date: Sat, 29 Jan 2000 03:16:54 +0000 Subject: Add a manual page for the ELF dynamic linker. I initially created rtld.1 by means of a repository copy from "src/libexec/rtld-aout/rtld.1". Then I edited it to make it (more) accurate for the ELF dynamic linker. --- libexec/rtld-elf/rtld.1 | 118 ++++++++---------------------------------------- 1 file changed, 20 insertions(+), 98 deletions(-) (limited to 'libexec/rtld-elf/rtld.1') diff --git a/libexec/rtld-elf/rtld.1 b/libexec/rtld-elf/rtld.1 index f937321..7d5618c 100644 --- a/libexec/rtld-elf/rtld.1 +++ b/libexec/rtld-elf/rtld.1 @@ -28,25 +28,21 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd June 27, 1995 +.Dd January 28, 2000 .Dt RTLD 1 .Os FreeBSD .Sh NAME -.Nm ld.so , +.Nm ld-elf.so.1 , .Nm rtld .Nd run-time link-editor .Sh DESCRIPTION .Nm -is a self-contained, position independent program image providing run-time +is a self-contained shared object providing run-time support for loading and link-editing shared objects into a process' -address space. It uses the data structures -.Po -see -.Xr link 5 -.Pc +address space. It is also commonly known as the dynamic linker. +It uses the data structures contained within dynamically linked programs to determine which shared -libraries are needed and loads them at a convenient virtual address -using the +libraries are needed and loads them using the .Xr mmap 2 system call. .Pp @@ -54,54 +50,24 @@ After all shared libraries have been successfully loaded, .Nm proceeds to resolve external references from both the main program and all objects loaded. A mechanism is provided for initialization routines -to be called, on a per-object basis, giving a shared object an opportunity -to perform any extra set-up, before execution of the program proper begins. +to be called on a per-object basis, giving a shared object an opportunity +to perform any extra set-up before execution of the program proper begins. This is useful for C++ libraries that contain static constructors. .Pp .Nm -is itself a shared object that is initially loaded by the startup module -.Em crt0 . -Since -.Xr a.out 5 -formats do not provide easy access to the file header from within a running -process, -.Em crt0 -uses the special symbol -.Va _DYNAMIC -to determine whether a program is in fact dynamically linked or not. Whenever -the linker -.Xr ld 1 -has relocated this symbol to a location other than 0, -.Em crt0 -assumes the services of -.Nm -are needed -.Po -see -.Xr link 5 -for details -.Pc \&. -.Em crt0 -passes control to -.Nm -\&'s entry point before the program's -.Fn main -routine is called. Thus, -.Nm -can complete the link-editing process before the dynamic program calls upon -services of any dynamic library. +itself is loaded by the kernel together with any dynamically-linked +program that is to be executed. The kernel transfers control to the +dynamic linker. After the dynamic linker has finished loading, +relocating, and initializing the program and its required shared +objects, it transfers control to the entry point of the program. .Pp -To quickly locate the required shared objects in the filesystem, +To locate the required shared objects in the filesystem, .Nm may use a .Dq hints -file, prepared by the +file prepared by the .Xr ldconfig 8 -utility, in which the full path specification of the shared objects can be -looked up by hashing on the 3-tuple -.Ao -library-name, major-version-number, minor-version-number -.Ac \&. +utility. .Pp .Nm recognizes a number of environment variables that can be used to modify @@ -113,7 +79,8 @@ A colon separated list of directories, overriding the default search path for shared libraries. This is ignored for set-user-ID and set-group-ID programs. .It Ev LD_PRELOAD -A colon separated list of shared libraries, to be linked in before any +A list of shared libraries, separated by colons and/or white space, +to be linked in before any other shared libraries. If the directory is not specified then the directories specified by LD_LIBRARY_PATH will be searched first followed by the set of built-in standard directories. @@ -127,38 +94,6 @@ of each function. .Ev LD_BIND_NOW increases the start-up time of a program, but it avoids run-time surprises caused by unexpectedly undefined functions. -.It Ev LD_WARN_NON_PURE_CODE -When set to a nonempty string, issue a warning whenever a link-editing -operation requires modification of the text segment of some loaded -object. This is usually indicative of an incorrectly built library. -.It Ev LD_SUPPRESS_WARNINGS -When set to a nonempty string, no warning messages of any kind are -issued. Normally, a warning is given if satisfactorily versioned -library could not be found. -.It Ev LD_IGNORE_MISSING_OBJECTS -When set to a nonempty string, makes it a nonfatal condition if -one or more required shared objects cannot be loaded. -Loading and execution proceeds using the objects that are -available. -A warning is produced for each missing object, unless the environment -variable -.Ev LD_SUPPRESS_WARNINGS -is set to a nonempty string. -.Pp -This is ignored for set-user-ID and set-group-ID programs. -.Pp -Missing shared objects can be ignored without errors if all the -following conditions hold: -.Bl -bullet -.It -They do not supply definitions for any required data symbols. -.It -No functions defined by them are called during program execution. -.It -The environment variable -.Ev LD_BIND_NOW -is unset or is set to the empty string. -.El .It Ev LD_TRACE_LOADED_OBJECTS When set to a nonempty string, causes .Nm @@ -188,8 +123,6 @@ The value of the environment variable The library name. .It \&%m The library's major version number. -.It \&%n -The library's minor version number. .It \&%p The full pathname as determined by .Nm rtld Ns 's @@ -203,23 +136,12 @@ Additionally, and .Sy \et are recognized and have their usual meaning. -.\" .It Ev LD_NO_INTERN_SEARCH -.\" When set, -.\" .Nm -.\" does not process any internal search paths that were recorded in the -.\" executable. -.\" .It Ev LD_NOSTD_PATH -.\" When set, do not include a set of built-in standard directory paths for -.\" searching. This might be useful when running on a system with a completely -.\" non-standard filesystem layout. .El .Pp .Sh FILES -/var/run/ld.so.hints +/var/run/ld-elf.so.hints .Pp .Sh SEE ALSO +.Xr elf 5 , .Xr ld 1 , -.Xr link 5 , .Xr ldconfig 8 -.Sh HISTORY -The shared library model employed first appeared in SunOS 4.0 -- cgit v1.1