libexec/rtld-elf/rtld.1

   1 .\" $FreeBSD: src/libexec/rtld-elf/rtld.1,v 1.18.2.7 2002/01/10 17:51:28 ru 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 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 January 28, 2000
  32 .Dt RTLD 1
  33 .Os
  34 .Sh NAME
  35 .Nm ld-elf.so.1 ,
  36 .Nm rtld
  37 .Nd run-time link-editor
  38 .Sh DESCRIPTION
  39 .Nm
  40 is a self-contained shared object providing run-time
  41 support for loading and link-editing shared objects into a process'
  42 address space.
  43 It is also commonly known as the dynamic linker.
  44 It uses the data structures
  45 contained within dynamically linked programs to determine which shared
  46 libraries are needed and loads them using the
  47 .Xr mmap 2
  48 system call.
  49 .Pp
  50 After all shared libraries have been successfully loaded,
  51 .Nm
  52 proceeds to resolve external references from both the main program and
  53 all objects loaded.
  54 A mechanism is provided for initialization routines
  55 to be called on a per-object basis, giving a shared object an opportunity
  56 to perform any extra set-up before execution of the program proper begins.
  57 This is useful for C++ libraries that contain static constructors.
  58 .Pp
  59 .Nm
  60 itself is loaded by the kernel together with any dynamically-linked
  61 program that is to be executed.
  62 The kernel transfers control to the
  63 dynamic linker.
  64 After the dynamic linker has finished loading,
  65 relocating, and initializing the program and its required shared
  66 objects, it transfers control to the entry point of the program.
  67 .Pp
  68 To locate the required shared objects in the filesystem,
  69 .Nm
  70 may use a
  71 .Dq hints
  72 file prepared by the
  73 .Xr ldconfig 8
  74 utility.
  75 .Pp
  76 .Nm
  77 recognizes a number of environment variables that can be used to modify
  78 its behaviour as follows:
  79 .Pp
  80 .Bl -tag -width ".Ev LD_LIBRARY_PATH"
  81 .It Ev LD_LIBRARY_PATH
  82 A colon separated list of directories, overriding the default search path
  83 for shared libraries.
  84 This is ignored for set-user-ID and set-group-ID programs.
  85 .It Ev LD_PRELOAD
  86 A list of shared libraries, separated by colons and/or white space,
  87 to be linked in before any
  88 other shared libraries.
  89 If the directory is not specified then
  90 the directories specified by
  91 .Ev LD_LIBRARY_PATH
  92 will be searched first
  93 followed by the set of built-in standard directories.
  94 This is ignored for set-user-ID and set-group-ID programs.
  95 .It Ev LD_BIND_NOW
  96 When set to a nonempty string, causes
  97 .Nm
  98 to relocate all external function calls before starting execution of the
  99 program.
 100 Normally, function calls are bound lazily, at the first call
 101 of each function.
 102 .Ev LD_BIND_NOW
 103 increases the start-up time of a program, but it avoids run-time
 104 surprises caused by unexpectedly undefined functions.
 105 .It Ev LD_TRACE_LOADED_OBJECTS
 106 When set to a nonempty string, causes
 107 .Nm
 108 to exit after loading the shared objects and printing a summary which includes
 109 the absolute pathnames of all objects, to standard output.
 110 .It Ev LD_TRACE_LOADED_OBJECTS_FMT1
 111 .It Ev LD_TRACE_LOADED_OBJECTS_FMT2
 112 When set, these variables are interpreted as format strings a la
 113 .Xr printf 3
 114 to customize the trace output and are used by
 115 .Xr ldd 1 Ns 's
 116 .Fl f
 117 option and allows
 118 .Xr ldd 1
 119 to be operated as a filter more conveniently.
 120 The following conversions can be used:
 121 .Bl -tag -width 4n
 122 .It Li %a
 123 The main program's name
 124 (also known as
 125 .Dq __progname ) .
 126 .It Li \&%A
 127 The value of the environment variable
 128 .Ev LD_TRACE_LOADED_OBJECTS_PROGNAME
 129 .It Li %o
 130 The library name.
 131 .It Li %m
 132 The library's major version number.
 133 .It Li %p
 134 The full pathname as determined by
 135 .Nm rtld Ns 's
 136 library search rules.
 137 .It Li %x
 138 The library's load address.
 139 .El
 140 .Pp
 141 Additionally,
 142 .Ql \en
 143 and
 144 .Ql \et
 145 are recognized and have their usual meaning.
 146 .El
 147 .Sh FILES
 148 .Bl -tag -width indent
 149 .It Pa /var/run/ld-elf.so.hints
 150 .El
 151 .Sh SEE ALSO
 152 .Xr ld 1 ,
 153 .Xr ldd 1 ,
 154 .Xr elf 5 ,
 155 .Xr ldconfig 8