1.\" Copyright (c) 2003 Matthew N. Dodd <winter@jurai.net> 2.\" Copyright (c) 2013 Dag-Erling Smørgrav 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd September 16, 2013 29.Dt LIBMAP.CONF 5 30.Os 31.Sh NAME 32.Nm libmap.conf 33.Nd "configuration file for dynamic object dependency mapping" 34.Sh DESCRIPTION 35The 36.Nm libmap 37functionality of 38.Xr ld-elf.so.1 1 39allows dynamic object dependencies to be mapped to arbitrary names. 40.Pp 41Each line in 42.Pa /etc/libmap.conf 43can have one of five forms: 44.Bl -tag -width indent 45.It Ar origin Ar target 46Whenever a dependency on 47.Ar origin 48is encountered while loading a dynamic object, use 49.Ar target 50instead of searching for 51.Ar origin 52in the normal library search paths. 53.It Ar path1 Ar path2 54When iterating through a library search path, replace any element that 55matches 56.Ar path1 57exactly with 58.Ar path2 . 59.It Bq Ar constraint 60Apply 61.Ar constraint 62to all subsequent mappings until the next constraint line or the end 63of the file. 64See the 65.Sx Constraints 66section for details. 67.It Cm include Ar file 68Parse the contents of 69.Ar file 70before continuing with the current file. 71Nesting depth is limited only by available memory, but each file 72encountered is processed only once, and loops are silently ignored. 73.It Cm includedir Ar dir 74Recurse through 75.Ar dir 76and parse the contents of any file that ends in 77.Pa .conf 78before continuing with the current file. 79Nesting depth is limited only by available memory, but each directory 80or file encountered is processed only once, and loops are silently 81ignored. 82.El 83.Ss Constraints 84Constrained mappings only apply when processing binaries or libraries 85that satisfy the constraint. 86There are three types of constraints: 87.Bl -tag -width indent 88.It Exact 89The constraint is matched literally so that only an executable with an 90identical fully qualified pathname will satisfy the constraint. 91This means that the executable 92.Pa /usr/bin/foo 93will not satisfy the constraint 94.Bq Pa /usr/bin/./foo , 95and vice-versa. 96This is the default constraint type. 97.It Basename 98A constraint with no path is matched against the basename of the 99executable. 100For instance, the constraint 101.Bq Pa foo 102will match 103.Pa /bin/foo , 104.Pa /usr/local/sbin/foo , 105or any other executable named 106.Pa foo , 107no matter what directory it is in. 108.It Directory 109A constraint with a trailing slash is satisfied if the full pathname 110begins with the constraint string. 111For instance, the constraint 112.Bq Pa /usr/bin/ 113will match any executable with a path starting with 114.Pa /usr/bin/ . 115.El 116.Pp 117Note that the constraints are matched against the path that was passed 118as the first argument to whichever 119.Xr exec 3 120function was used to execute the binary in question. 121Most programs executed from a shell are run without a full path, via 122.Xr execvp 3 123or similar, so the basename constraint type is the most useful. 124.Pp 125.Bf -symbolic 126WARNING! 127Constraints apply to all mappings until the next constraint or the end 128of the file. 129Hence, unconstrained mappings must be placed at the top of the file. 130.Ef 131.Ss ABI compatibility 132On 64-bit architectures that provide 32-bit binary compatibility, the 133mappings in 134.Pa /etc/libmap.conf 135apply only to 64-bit binaries. 136Mappings for 32-bit binaries must be placed in 137.Pa /etc/libmap32.conf . 138.Sh FILES 139.Bl -tag -width ".Pa /etc/libmap32.conf" -compact 140.It Pa /etc/libmap.conf 141The libmap configuration file. 142.It Pa /etc/libmap32.conf 143The libmap configuration file for 32-bit binaries on 64-bit system. 144.El 145.Sh EXAMPLES 146.Bd -literal 147# 148# origin target 149# 150libc_r.so.6 libpthread.so.2 # Everything that uses 'libc_r' 151libc_r.so libpthread.so # now uses 'libpthread' 152 153[/tmp/mplayer] # Test version of mplayer uses libc_r 154libpthread.so.2 libc_r.so.6 155libpthread.so libc_r.so 156 157[/usr/local/jdk1.4.1/] # All Java 1.4.1 programs use libthr 158 # This works because "javavms" executes 159 # programs with the full pathname 160libpthread.so.2 libthr.so.2 161libpthread.so libthr.so 162 163# Glue for Linux-only EPSON printer .so to be loaded into cups, etc. 164[/usr/local/lib/pips/libsc80c.so] 165libc.so.6 pluginwrapper/pips.so 166libdl.so.2 pluginwrapper/pips.so 167.Ed 168.Sh SEE ALSO 169.Xr ldd 1 , 170.Xr rtld 1 171.Sh HISTORY 172The 173.Nm libmap 174mechanism first appeared in 175.Fx 5.1 . 176.Sh AUTHORS 177.An -nosplit 178This manual page was written by 179.An Matthew N. Dodd Aq Mt winter@jurai.net 180and extensively rewritten by 181.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . 182