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.Dd September 16, 2013 27.Dt LIBMAP.CONF 5 28.Os 29.Sh NAME 30.Nm libmap.conf 31.Nd "configuration file for dynamic object dependency mapping" 32.Sh DESCRIPTION 33The 34.Nm libmap 35functionality of 36.Xr ld-elf.so.1 1 37allows dynamic object dependencies to be mapped to arbitrary names. 38.Pp 39Each line in 40.Pa /etc/libmap.conf 41can have one of five forms: 42.Bl -tag -width indent 43.It Ar origin Ar target 44Whenever a dependency on 45.Ar origin 46is encountered while loading a dynamic object, use 47.Ar target 48instead of searching for 49.Ar origin 50in the normal library search paths. 51.It Ar path1 Ar path2 52When iterating through a library search path, replace any element that 53matches 54.Ar path1 55exactly with 56.Ar path2 . 57.It Bq Ar constraint 58Apply 59.Ar constraint 60to all subsequent mappings until the next constraint line or the end 61of the file. 62See the 63.Sx Constraints 64section for details. 65.It Cm include Ar file 66Parse the contents of 67.Ar file 68before continuing with the current file. 69Nesting depth is limited only by available memory, but each file 70encountered is processed only once, and loops are silently ignored. 71.It Cm includedir Ar dir 72Recurse through 73.Ar dir 74and parse the contents of any file that ends in 75.Pa .conf 76before continuing with the current file. 77Nesting depth is limited only by available memory, but each directory 78or file encountered is processed only once, and loops are silently 79ignored. 80.El 81.Ss Constraints 82Constrained mappings only apply when processing binaries or libraries 83that satisfy the constraint. 84There are three types of constraints: 85.Bl -tag -width indent 86.It Exact 87The constraint is matched literally so that only an executable with an 88identical fully qualified pathname will satisfy the constraint. 89This means that the executable 90.Pa /usr/bin/foo 91will not satisfy the constraint 92.Bq Pa /usr/bin/./foo , 93and vice-versa. 94This is the default constraint type. 95.It Basename 96A constraint with no path is matched against the basename of the 97executable. 98For instance, the constraint 99.Bq Pa foo 100will match 101.Pa /bin/foo , 102.Pa /usr/local/sbin/foo , 103or any other executable named 104.Pa foo , 105no matter what directory it is in. 106.It Directory 107A constraint with a trailing slash is satisfied if the full pathname 108begins with the constraint string. 109For instance, the constraint 110.Bq Pa /usr/bin/ 111will match any executable with a path starting with 112.Pa /usr/bin/ . 113.El 114.Pp 115Note that the constraints are matched against the path that was passed 116as the first argument to whichever 117.Xr exec 3 118function was used to execute the binary in question. 119Most programs executed from a shell are run without a full path, via 120.Xr execvp 3 121or similar, so the basename constraint type is the most useful. 122.Pp 123.Bf -symbolic 124WARNING! 125Constraints apply to all mappings until the next constraint or the end 126of the file. 127Hence, unconstrained mappings must be placed at the top of the file. 128.Ef 129.Ss ABI compatibility 130On 64-bit architectures that provide 32-bit binary compatibility, the 131mappings in 132.Pa /etc/libmap.conf 133apply only to 64-bit binaries. 134Mappings for 32-bit binaries must be placed in 135.Pa /etc/libmap32.conf . 136.Sh FILES 137.Bl -tag -width ".Pa /etc/libmap32.conf" -compact 138.It Pa /etc/libmap.conf 139The libmap configuration file. 140.It Pa /etc/libmap32.conf 141The libmap configuration file for 32-bit binaries on 64-bit system. 142.El 143.Sh EXAMPLES 144.Bd -literal 145# 146# origin target 147# 148libc_r.so.6 libpthread.so.2 # Everything that uses 'libc_r' 149libc_r.so libpthread.so # now uses 'libpthread' 150 151[/tmp/mplayer] # Test version of mplayer uses libc_r 152libpthread.so.2 libc_r.so.6 153libpthread.so libc_r.so 154 155[/usr/local/jdk1.4.1/] # All Java 1.4.1 programs use libthr 156 # This works because "javavms" executes 157 # programs with the full pathname 158libpthread.so.2 libthr.so.2 159libpthread.so libthr.so 160 161# Glue for Linux-only EPSON printer .so to be loaded into cups, etc. 162[/usr/local/lib/pips/libsc80c.so] 163libc.so.6 pluginwrapper/pips.so 164libdl.so.2 pluginwrapper/pips.so 165.Ed 166.Sh SEE ALSO 167.Xr ldd 1 , 168.Xr rtld 1 169.Sh HISTORY 170The 171.Nm libmap 172mechanism first appeared in 173.Fx 5.1 . 174.Sh AUTHORS 175.An -nosplit 176This manual page was written by 177.An Matthew N. Dodd Aq Mt winter@jurai.net 178and extensively rewritten by 179.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . 180