1.\" Copyright (c) 2003 Matthew N. Dodd <winter@jurai.net> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd January 31, 2004 28.Dt LIBMAP.CONF 5 29.Os 30.Sh NAME 31.Nm libmap.conf 32.Nd "configuration file for dynamic object dependency mapping" 33.Sh DESCRIPTION 34The 35.Nm libmap 36functionality of 37.Xr ld-elf.so.1 1 38allows dynamic object dependencies to be mapped to arbitrary 39names. 40.Pp 41The configuration file consists of two whitespace separated columns; the 42left hand side containing the mapping candidate and the right hand 43side containing the mapping. 44Dependencies are matched against candidates and replaced with the mappings. 45.Pp 46Constrained mappings may be specified by enclosing the name of the 47executable or library in brackets. 48All mappings following a constraint will only be evaluated for that constraint. 49Constraints can be one of three types: 50.Bl -tag -width indent 51.It Exact 52The constraint is matched literally so that only an executable with an 53identical fully qualified pathname will match the constraint. 54This means that the executable 55.Pa /usr/bin/foo 56will not match a constraint for 57.Pa /usr/bin/./foo 58and vice-versa. 59This is the default constraint type. 60.It Basename 61A constraint with no path is matched against the basename of the 62executable. 63.Pa foo 64will match 65.Pa /bin/foo , 66.Pa /usr/local/sbin/foo , 67or any other executable named 68.Pa foo , 69no matter what its path is. 70.It Directory 71A constraint with a trailing slash is prefix-matched against the full 72pathname of the executable. 73.Pa /usr/bin/ 74will match any executable with a path starting with /usr/bin. 75.El 76.Pp 77Note that the executable path matched against is the 78.Fa path 79parameter in an 80.Fn exec* 81function call. 82The Directory or Exact constraints can only match when the executable 83is called with a full pathname. 84Most programs executed from a shell are run without a full path, via 85.Fn exec*p , 86so the Basename constraint type is the most useful. 87.Pp 88WARNING! 89Constrained mappings must never appear first in the configuration file. 90While there is a way to specify the 91.Dq default 92constraint, its use is not recommended. 93.Pp 94The most common use at the date of writing is for allowing multiple 95.Tn POSIX 96threading libraries to be used on a system without relinking or 97changing symlinks. 98.Pp 99On 64-bit architectures that provide 32-bit runtime support, 100the libmap mechanism is available for 32-bit binaries too. 101The mappings has to be written into separate configuration file 102.Pa /etc/libmap32.conf . 103Currently only supported on amd64. 104.Pp 105This mechanism has also been used to create shims to allow Linux 106shared libraries to be dynamically loaded into 107.Fx 108binaries. 109In this case, an Exact constraint is used for the Linux shared library, 110mapping libraries it depends on to a wrapper. 111The wrapper then defines any needed symbols for the Linux shared library 112and relies on its libraries not being mapped to provide actual 113implementations. 114It appears that only libraries loaded via 115.Xr dlopen 3 116will work correctly. 117The symbol version information in shared libraries is checked at 118link time, but at run time the version information is currently 119ignored. 120.Sh FILES 121.Bl -tag -width ".Pa /etc/libmap32.conf" -compact 122.It Pa /etc/libmap.conf 123The libmap configuration file. 124.It Pa /etc/libmap32.conf 125The libmap configuration file for 32-bit binaries on 64-bit system. 126.El 127.Sh EXAMPLES 128.Bd -literal 129# /etc/libmap.conf 130# 131# candidate mapping 132# 133libc_r.so.6 libpthread.so.2 # Everything that uses 'libc_r' 134libc_r.so libpthread.so # now uses 'libpthread' 135 136[/tmp/mplayer] # Test version of mplayer uses libc_r 137libpthread.so.2 libc_r.so.6 138libpthread.so libc_r.so 139 140[/usr/local/jdk1.4.1/] # All Java 1.4.1 programs use libthr 141 # This works because "javavms" executes 142 # programs with the full pathname 143libpthread.so.2 libthr.so.2 144libpthread.so libthr.so 145 146# Glue for Linux-only EPSON printer .so to be loaded into cups, etc. 147[/usr/local/lib/pips/libsc80c.so] 148libc.so.6 pluginwrapper/pips.so 149libdl.so.2 pluginwrapper/pips.so 150.Ed 151.Sh SEE ALSO 152.Xr ldd 1 , 153.Xr rtld 1 154.Sh HISTORY 155The 156.Nm 157manual page and 158.Nm libmap 159functionality first appeared in 160.Fx 5.1 . 161.Sh AUTHORS 162This manual page was written by 163.An Matthew N. Dodd Aq winter@jurai.net . 164