Dynamic object dependency mapping: libmap.

This is an optional feature, disabled by default.

This will be useful to people testing the various POSIX threading
libraries under -CURRENT but can easily serve other needs.

2 files changed, 112 insertions, 1 deletions

diff --git a/share/man/man5/Makefile b/share/man/man5/Makefile
index dc3765d..34a316b 100644
--- a/share/man/man5/Makefile
+++ b/share/man/man5/Makefile
@@ -6,7 +6,7 @@ MAN=	a.out.5 acct.5 core.5 devfs.5 device.hints.5 \
 	dir.5 disktab.5 drivers.conf.5 \
 	elf.5 ethers.5 fbtab.5 fdescfs.5 forward.5 fs.5 fstab.5 group.5 \
 	hesiod.conf.5 \
-	hosts.5 hosts.equiv.5 hosts.lpd.5 intro.5 link.5 \
+	hosts.5 hosts.equiv.5 hosts.lpd.5 intro.5 libmap.conf.5 link.5 \
 	linprocfs.5 mailer.conf.5 make.conf.5 moduli.5 motd.5 msdosfs.5 \
 	networks.5 \
 	nsswitch.conf.5 \
diff --git a/share/man/man5/libmap.conf.5 b/share/man/man5/libmap.conf.5
new file mode 100644
index 0000000..5acde5d
--- /dev/null
+++ b/share/man/man5/libmap.conf.5
@@ -0,0 +1,111 @@
+.\" Copyright (c) 2003 Matthew N. Dodd <winter@jurai.net>
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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.
+.\"
+.\" $FreeBSD$
+.\"
+.\" Note: The date here should be updated whenever a non-trivial
+.\" change is made to the manual page.
+.Dd April 7, 2003
+.Dt LIBMAP.CONF 5
+.Os
+.Sh NAME
+.Nm libmap.conf
+.Nd "configuration file for dynamic object dependency mapping"
+.Sh DESCRIPTION
+The
+.Em libmap
+functionality of
+.Nm ld-elf.so.1
+allows dynamic object dependencies to be mapped to arbitrary
+names.
+.Pp
+The configuration file consists of two whitespace separated columns; the 
+left hand side containing the mapping candidate and the right hand
+side containing the mapping.  Dependencies are matched against candidates
+and replaced with the mappings.
+.Pp
+Constrained mappings may be specified by enclosing the name of the
+executable or library in brackets.  All mappings following a constraint
+will only be evaluated for that constraint.  Currently, constraints
+are matched literally so that an executable with a fully qualified pathname 
+will only match the same constraint.  This means that
+.Em /usr/bin/foo
+will not match a constraint for
+.Em foo
+and vise-versa.
+.Pp
+WARNING!  Constrained mappings must never appear first in the configuration
+file.  While there is a way to specify the
+.Dq default
+constraint, its use is not recommended.
+.Pp
+The most common use at the date of writing is for allowing multiple
+POSIX threading libraries to be used on a system without relinking or
+changing symlinks.
+.Pp
+In order to enable this feature please see 
+.Pa src/libexec/rtld-elf/Makefile .
+.Sh EXAMPLE
+.Bd -literal
+
+# /etc/libmap.conf
+#
+# candidate		mapping
+#
+libc_r.so.5		libthr.so.1	# Everything uses 'libthr'
+libc_r.so		libthr.so
+
+[/usr/local/bin/mplayer]		# 'mplayer' uses libc_r.
+libc_r.so.5		libc_r.so.5
+libc_r.so		libc_r.so
+
+[mplayer]
+libc_r.so.5		libc_r.so.5
+libc_r.so		libc_r.so
+
+[/usr/local/sbin/httpd]			# Apache uses libkse
+libc_r.so.5		libkse.so.1
+libc_r.so		libkse.so
+
+[httpd]
+libc_r.so.5		libkse.so.1
+libc_r.so		libkse.so
+.Ed
+.Sh FILES
+.Bl -tag -width ".Pa /etc/libmap.conf" -compact
+.It Pa /etc/libmap.conf
+The libmap configuration file.
+.El
+.Sh SEE ALSO
+.Xr rtld 1
+.Xr ldd 1
+.Sh HISTORY
+The
+.Nm
+manual page and libmap.conf functionality first appeared in
+.Fx 5.1 .
+.Sh AUTHORS
+This
+manual page was written by
+.An Matthew N. Dodd <winter@jurai.net> .