diff options
Diffstat (limited to 'libexec/rtld-aout/rtld.1aout')
| -rw-r--r-- | libexec/rtld-aout/rtld.1aout | 224 |
1 files changed, 224 insertions, 0 deletions
diff --git a/libexec/rtld-aout/rtld.1aout b/libexec/rtld-aout/rtld.1aout new file mode 100644 index 0000000..dbd4dde --- /dev/null +++ b/libexec/rtld-aout/rtld.1aout @@ -0,0 +1,224 @@ +.\" $Id: rtld.1,v 1.13 1997/02/22 15:46:47 peter Exp $ +.\" +.\" Copyright (c) 1995 Paul Kranenburg +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgment: +.\" This product includes software developed by Paul Kranenburg. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (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 +.Dt RTLD 1 +.Os FreeBSD +.Sh NAME +.Nm ld.so +.Nd run-time link-editor +.Sh DESCRIPTION +.Nm +is a self-contained, position independent program image 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 +contained within dynamically linked programs to determine which shared +libraries are needed and loads them at a convenient virtual address +using the +.Xr mmap 2 +system call. +.Pp +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. +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. +.Pp +To quickly locate the required shared objects in the filesystem, +.Nm +may use a +.Dq hints +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 \&. +.Pp +.Nm +recognises a number of environment variables that can be used to modify +its behaviour as follows: +.Pp +.Bl -tag -width "LD_IGNORE_MISSING_OBJECTS" +.It Ev LD_LIBRARY_PATH +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 +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. +This is ignored for set-user-ID and set-group-ID programs. +.It Ev LD_BIND_NOW +When set to a nonempty string, causes +.Nm +to relocate all external function calls before starting execution of the +program. Normally, function calls are bound lazily, at the first call +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 +to exit after loading the shared objects and printing a summary which includes +the absolute pathnames of all objects, to standard output. +.It Ev LD_TRACE_LOADED_OBJECTS_FMT1 +.It Ev LD_TRACE_LOADED_OBJECTS_FMT2 +When set, these variables are interpreted as format strings a la +.Xr printf 3 +to customize the trace output and are used by +.Xr ldd 1 's +.Fl f +option and allows +.Xr ldd 1 +to be operated as a filter more conveniently. +The following conversions can be used: +.Bl -tag -indent "LD_TRACE_LOADED_OBJECTS_FMT1 " -width "xxxx" +.It \&%a +The main program's name +.Po also known as +.Dq __progname +.Pc . +.It \&%A +The value of the environment variable +.Ev LD_TRACE_LOADED_OBJECTS_PROGNAME +.It \&%o +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 +library search rules. +.It \&%x +The library's load address. +.El +.Pp +Additionally, +.Sy \en +and +.Sy \et +are recognised 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 +.Pp +.Sh SEE ALSO +.Xr ld 1 , +.Xr link 5 , +.Xr ldconfig 8 +.Sh HISTORY +The shared library model employed first appeared in SunOS 4.0 |
