| 1 | .\" $FreeBSD: src/libexec/rtld-elf/rtld.1,v 1.18.2.7 2002/01/10 17:51:28 ru Exp $ |
| 2 | .\" $DragonFly: src/libexec/rtld-elf/rtld.1,v 1.5 2006/02/11 21:32:41 swildner Exp $ |
| 3 | .\" |
| 4 | .\" Copyright (c) 1995 Paul Kranenburg |
| 5 | .\" All rights reserved. |
| 6 | .\" |
| 7 | .\" Redistribution and use in source and binary forms, with or without |
| 8 | .\" modification, are permitted provided that the following conditions |
| 9 | .\" are met: |
| 10 | .\" 1. Redistributions of source code must retain the above copyright |
| 11 | .\" notice, this list of conditions and the following disclaimer. |
| 12 | .\" 2. Redistributions in binary form must reproduce the above copyright |
| 13 | .\" notice, this list of conditions and the following disclaimer in the |
| 14 | .\" documentation and/or other materials provided with the distribution. |
| 15 | .\" 3. All advertising materials mentioning features or use of this software |
| 16 | .\" must display the following acknowledgment: |
| 17 | .\" This product includes software developed by Paul Kranenburg. |
| 18 | .\" 3. The name of the author may not be used to endorse or promote products |
| 19 | .\" derived from this software without specific prior written permission |
| 20 | .\" |
| 21 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR |
| 22 | .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
| 23 | .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
| 24 | .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, |
| 25 | .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
| 26 | .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 27 | .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 28 | .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 29 | .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
| 30 | .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 31 | .\" |
| 32 | .Dd January 28, 2000 |
| 33 | .Dt RTLD 1 |
| 34 | .Os |
| 35 | .Sh NAME |
| 36 | .Nm ld-elf.so.1 , |
| 37 | .Nm ld-elf.so.2 , |
| 38 | .Nm rtld |
| 39 | .Nd run-time link-editor |
| 40 | .Sh DESCRIPTION |
| 41 | .Nm |
| 42 | is a self-contained shared object providing run-time |
| 43 | support for loading and link-editing shared objects into a process' |
| 44 | address space. |
| 45 | It is also commonly known as the dynamic linker. |
| 46 | It uses the data structures |
| 47 | contained within dynamically linked programs to determine which shared |
| 48 | libraries are needed and loads them using the |
| 49 | .Xr mmap 2 |
| 50 | system call. |
| 51 | .Pp |
| 52 | After all shared libraries have been successfully loaded, |
| 53 | .Nm |
| 54 | proceeds to resolve external references from both the main program and |
| 55 | all objects loaded. |
| 56 | A mechanism is provided for initialization routines |
| 57 | to be called on a per-object basis, giving a shared object an opportunity |
| 58 | to perform any extra set-up before execution of the program proper begins. |
| 59 | This is useful for C++ libraries that contain static constructors. |
| 60 | .Pp |
| 61 | .Nm |
| 62 | itself is loaded by the kernel together with any dynamically-linked |
| 63 | program that is to be executed. |
| 64 | The kernel transfers control to the |
| 65 | dynamic linker. |
| 66 | After the dynamic linker has finished loading, |
| 67 | relocating, and initializing the program and its required shared |
| 68 | objects, it transfers control to the entry point of the program. |
| 69 | .Pp |
| 70 | To locate the required shared objects in the filesystem, |
| 71 | .Nm |
| 72 | may use a |
| 73 | .Dq hints |
| 74 | file prepared by the |
| 75 | .Xr ldconfig 8 |
| 76 | utility. |
| 77 | .Pp |
| 78 | .Nm |
| 79 | recognizes a number of environment variables that can be used to modify |
| 80 | its behaviour as follows: |
| 81 | .Pp |
| 82 | .Bl -tag -width ".Ev LD_LIBRARY_PATH" |
| 83 | .It Ev LD_LIBRARY_PATH |
| 84 | A colon separated list of directories, overriding the default search path |
| 85 | for shared libraries. |
| 86 | This is ignored for set-user-ID and set-group-ID programs. |
| 87 | .It Ev LD_PRELOAD |
| 88 | A list of shared libraries, separated by colons and/or white space, |
| 89 | to be linked in before any |
| 90 | other shared libraries. |
| 91 | If the directory is not specified then |
| 92 | the directories specified by |
| 93 | .Ev LD_LIBRARY_PATH |
| 94 | will be searched first |
| 95 | followed by the set of built-in standard directories. |
| 96 | This is ignored for set-user-ID and set-group-ID programs. |
| 97 | .It Ev LD_BIND_NOW |
| 98 | When set to a nonempty string, causes |
| 99 | .Nm |
| 100 | to relocate all external function calls before starting execution of the |
| 101 | program. |
| 102 | Normally, function calls are bound lazily, at the first call |
| 103 | of each function. |
| 104 | .Ev LD_BIND_NOW |
| 105 | increases the start-up time of a program, but it avoids run-time |
| 106 | surprises caused by unexpectedly undefined functions. |
| 107 | .It Ev LD_TRACE_LOADED_OBJECTS |
| 108 | When set to a nonempty string, causes |
| 109 | .Nm |
| 110 | to exit after loading the shared objects and printing a summary which includes |
| 111 | the absolute pathnames of all objects, to standard output. |
| 112 | .It Ev LD_TRACE_LOADED_OBJECTS_FMT1 |
| 113 | .It Ev LD_TRACE_LOADED_OBJECTS_FMT2 |
| 114 | When set, these variables are interpreted as format strings a la |
| 115 | .Xr printf 3 |
| 116 | to customize the trace output and are used by |
| 117 | .Xr ldd 1 Ns 's |
| 118 | .Fl f |
| 119 | option and allows |
| 120 | .Xr ldd 1 |
| 121 | to be operated as a filter more conveniently. |
| 122 | The following conversions can be used: |
| 123 | .Bl -tag -width 4n |
| 124 | .It Li %a |
| 125 | The main program's name |
| 126 | (also known as |
| 127 | .Dq __progname ) . |
| 128 | .It Li \&%A |
| 129 | The value of the environment variable |
| 130 | .Ev LD_TRACE_LOADED_OBJECTS_PROGNAME |
| 131 | .It Li %o |
| 132 | The library name. |
| 133 | .It Li %m |
| 134 | The library's major version number. |
| 135 | .It Li %p |
| 136 | The full pathname as determined by |
| 137 | .Nm rtld Ns 's |
| 138 | library search rules. |
| 139 | .It Li %x |
| 140 | The library's load address. |
| 141 | .El |
| 142 | .Pp |
| 143 | Additionally, |
| 144 | .Ql \en |
| 145 | and |
| 146 | .Ql \et |
| 147 | are recognized and have their usual meaning. |
| 148 | .El |
| 149 | .Sh DIFFERENCES BETWEEN .1 and .2 |
| 150 | ABI changes have been made to support TLS allocation and initialization |
| 151 | and to give threading libraries a chance to complete initialization of the |
| 152 | TCB prior to the calling of the _init() functions for the dynamically loaded |
| 153 | libraries. |
| 154 | .Sh FILES |
| 155 | .Bl -tag -width indent |
| 156 | .It Pa /var/run/ld-elf.so.hints |
| 157 | .El |
| 158 | .Sh SEE ALSO |
| 159 | .Xr ld 1 , |
| 160 | .Xr ldd 1 , |
| 161 | .Xr elf 5 , |
| 162 | .Xr ldconfig 8 |