Manpage for ELF ld.so, derived from a.out version, not yet complete

also points out missing features in the ELF ld.so.

2 files changed, 174 insertions, 2 deletions

diff --git a/libexec/ld.so/Makefile b/libexec/ld.so/Makefile
index c30982d03a0..b4197a59b5e 100644
--- a/libexec/ld.so/Makefile
+++ b/libexec/ld.so/Makefile
@@ -1,9 +1,8 @@
-#	$OpenBSD: Makefile,v 1.19 2003/04/17 03:40:45 drahn Exp $
+#	$OpenBSD: Makefile,v 1.20 2003/06/26 17:55:42 drahn Exp $
 
 SUBDIR=ldconfig ldd
 VPATH=${.CURDIR}/../../lib/libc/string:${.CURDIR}/../../sys/lib/libsa
 
-NOMAN=
 SRCS=	ldasm.S loader.c resolve.c dlfcn.c dl_printf.c rtld_machine.c
 SRCS+=	util.c sod.c strsep.c strtol.c dir.c
 .if (${MACHINE_ARCH} == "i386")
diff --git a/libexec/ld.so/ld.so.8 b/libexec/ld.so/ld.so.8
new file mode 100644
index 00000000000..7417f8228ab
--- /dev/null
+++ b/libexec/ld.so/ld.so.8
@@ -0,0 +1,173 @@
+.\"	$OpenBSD: ld.so.8,v 1.1 2003/06/26 17:55:42 drahn Exp $
+.\"	$NetBSD: rtld.1,v 1.2 1995/10/08 23:43:28 pk 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 acknowledgement:
+.\"      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 LD.SO 1
+.Os
+.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's
+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.
+
+<talk about CTORS/DTORS>
+
+.Pp
+.Nm
+is itself a shared object that is initially loaded by the the kernel
+<How it is run>
+.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 Ns \&.
+.Pp
+.Nm
+recognises a number of environment variables that can be used to modify
+its behaviour as follows:
+.Pp
+.Bl -tag -width "LD_TRACE_LOADED_OBJECTS_PROGNAME"
+.It Ev LD_LIBRARY_PATH
+A colon separated list of directories, overriding the default search path
+for shared libraries.
+This variable is ignored for set-user-ID and set-group-ID executables.
+.It Ev LD_PRELOAD
+A colon separate list of library names to load before any of the regular
+libraries are loaded.
+This variable is ignored for set-user-ID and set-group-ID executables.
+.It Ev LD_WARN_NON_PURE_CODE
+When set, 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.
+<not yet supported>
+.It Ev LD_SUPPRESS_WARNINGS
+When set, no warning messages of any kind are issued. Normally, a warning
+is given if satisfactorily versioned library could not be found.
+<not yet supported>
+.It Ev LD_TRACE_LOADED_OBJECTS
+When set, 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 Ns '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
+<not yet supported>
+.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 ld.so 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.
+<not yet supported>
+.It Ev LD_NO_INTERN_SEARCH
+When set,
+.Nm
+does not process any internal search paths that were recorded in the
+executable.
+<not yet supported>
+.It Ev LD_NOSTD_PATH
+<not yet supported>
+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
+.Bl -tag -width /var/run/ld.so.hintsXXX -compact
+.It Pa /var/run/ld.so.hints
+library location hints built by
+.Xr ldconfig 8
+.El
+.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.
+