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: head/share/man/man5/libmap.conf.5 157178 2006-03-27 14:37:54Z pav $ 26.\" 27.Dd February 20, 2011 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 99This mechanism has also been used to create shims to allow Linux 100shared libraries to be dynamically loaded into 101.Fx 102binaries. 103In this case, an Exact constraint is used for the Linux shared library, 104mapping libraries it depends on to a wrapper. 105The wrapper then defines any needed symbols for the Linux shared library 106and relies on its libraries not being mapped to provide actual 107implementations. 108It appears that only libraries loaded via 109.Xr dlopen 3 110will work correctly. 111The symbol version information in shared libraries is checked at 112link time, but at run time the version information is currently 113ignored. 114.Sh FILES 115.Bl -tag -width ".Pa /etc/libmap.conf" -compact 116.It Pa /etc/libmap.conf 117The libmap configuration file. 118.El 119.Sh EXAMPLES 120.Bd -literal 121# /etc/libmap.conf 122# 123# candidate mapping 124# 125libc_r.so.6 libpthread.so.2 # Everything that uses 'libc_r' 126libc_r.so libpthread.so # now uses 'libpthread' 127 128[/tmp/mplayer] # Test version of mplayer uses libc_r 129libpthread.so.2 libc_r.so.6 130libpthread.so libc_r.so 131 132[/usr/local/jdk1.4.1/] # All Java 1.4.1 programs use libthr 133 # This works because "javavms" executes 134 # programs with the full pathname 135libpthread.so.2 libthr.so.2 136libpthread.so libthr.so 137 138# Glue for Linux-only EPSON printer .so to be loaded into cups, etc. 139[/usr/local/lib/pips/libsc80c.so] 140libc.so.6 pluginwrapper/pips.so 141libdl.so.2 pluginwrapper/pips.so 142.Ed 143.Sh SEE ALSO 144.Xr ldd 1 , 145.Xr rtld 1 146.Sh HISTORY 147The 148.Nm 149manual page and 150.Nm libmap 151functionality first appeared in 152.Fx 5.1 . 153.Sh AUTHORS 154This manual page was written by 155.An Matthew N. Dodd Aq winter@jurai.net . 156