diff options
Diffstat (limited to 'share/man/man5/libmap.conf.5')
| -rw-r--r-- | share/man/man5/libmap.conf.5 | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/share/man/man5/libmap.conf.5 b/share/man/man5/libmap.conf.5 new file mode 100644 index 000000000000..6959ce2aaa93 --- /dev/null +++ b/share/man/man5/libmap.conf.5 @@ -0,0 +1,163 @@ +.\" 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$ +.\" +.Dd January 31, 2004 +.Dt LIBMAP.CONF 5 +.Os +.Sh NAME +.Nm libmap.conf +.Nd "configuration file for dynamic object dependency mapping" +.Sh DESCRIPTION +The +.Nm libmap +functionality of +.Xr ld-elf.so.1 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. +Constraints can be one of three types: +.Bl -tag -width indent +.It Exact +The constraint is matched literally so that only an executable with an +identical fully qualified pathname will match the constraint. +This means that the executable +.Pa /usr/bin/foo +will not match a constraint for +.Pa /usr/bin/./foo +and vice-versa. +This is the default constraint type. +.It Basename +A constraint with no path is matched against the basename of the +executable. +.Pa foo +will match +.Pa /bin/foo , +.Pa /usr/local/sbin/foo , +or any other executable named +.Pa foo , +no matter what its path is. +.It Directory +A constraint with a trailing slash is prefix-matched against the full +pathname of the executable. +.Pa /usr/bin/ +will match any executable with a path starting with /usr/bin. +.El +.Pp +Note that the executable path matched against is the +.Fa path +parameter in an +.Fn exec* +function call. +The Directory or Exact constraints can only match when the executable +is called with a full pathname. +Most programs executed from a shell are run without a full path, via +.Fn exec*p , +so the Basename constraint type is the most useful. +.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 +.Tn POSIX +threading libraries to be used on a system without relinking or +changing symlinks. +.Pp +On 64-bit architectures that provide 32-bit runtime support, +the libmap mechanism is available for 32-bit binaries too. +The mappings has to be written into separate configuration file +.Pa /etc/libmap32.conf . +Currently only supported on amd64. +.Pp +This mechanism has also been used to create shims to allow Linux +shared libraries to be dynamically loaded into +.Fx +binaries. +In this case, an Exact constraint is used for the Linux shared library, +mapping libraries it depends on to a wrapper. +The wrapper then defines any needed symbols for the Linux shared library +and relies on its libraries not being mapped to provide actual +implementations. +It appears that only libraries loaded via +.Xr dlopen 3 +will work correctly. +The symbol version information in shared libraries is checked at +link time, but at run time the version information is currently +ignored. +.Sh FILES +.Bl -tag -width ".Pa /etc/libmap32.conf" -compact +.It Pa /etc/libmap.conf +The libmap configuration file. +.It Pa /etc/libmap32.conf +The libmap configuration file for 32-bit binaries on 64-bit system. +.El +.Sh EXAMPLES +.Bd -literal +# /etc/libmap.conf +# +# candidate mapping +# +libc_r.so.6 libpthread.so.2 # Everything that uses 'libc_r' +libc_r.so libpthread.so # now uses 'libpthread' + +[/tmp/mplayer] # Test version of mplayer uses libc_r +libpthread.so.2 libc_r.so.6 +libpthread.so libc_r.so + +[/usr/local/jdk1.4.1/] # All Java 1.4.1 programs use libthr + # This works because "javavms" executes + # programs with the full pathname +libpthread.so.2 libthr.so.2 +libpthread.so libthr.so + +# Glue for Linux-only EPSON printer .so to be loaded into cups, etc. +[/usr/local/lib/pips/libsc80c.so] +libc.so.6 pluginwrapper/pips.so +libdl.so.2 pluginwrapper/pips.so +.Ed +.Sh SEE ALSO +.Xr ldd 1 , +.Xr rtld 1 +.Sh HISTORY +The +.Nm +manual page and +.Nm libmap +functionality first appeared in +.Fx 5.1 . +.Sh AUTHORS +This manual page was written by +.An Matthew N. Dodd Aq winter@jurai.net . |