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: head/share/man/man5/libmap.conf.5 255765 2013-09-21 21:03:52Z des $ 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.Sh FILES 132.Bl -tag -width ".Pa /etc/libmap.conf" -compact 133.It Pa /etc/libmap.conf 134The libmap configuration file. 135.El 136.Sh EXAMPLES 137.Bd -literal 138# 139# candidate target 140# 141libc_r.so.6 libpthread.so.2 # Everything that uses 'libc_r' 142libc_r.so libpthread.so # now uses 'libpthread' 143 144[/tmp/mplayer] # Test version of mplayer uses libc_r 145libpthread.so.2 libc_r.so.6 146libpthread.so libc_r.so 147 148[/usr/local/jdk1.4.1/] # All Java 1.4.1 programs use libthr 149 # This works because "javavms" executes 150 # programs with the full pathname 151libpthread.so.2 libthr.so.2 152libpthread.so libthr.so 153 154# Glue for Linux-only EPSON printer .so to be loaded into cups, etc. 155[/usr/local/lib/pips/libsc80c.so] 156libc.so.6 pluginwrapper/pips.so 157libdl.so.2 pluginwrapper/pips.so 158.Ed 159.Sh SEE ALSO 160.Xr ldd 1 , 161.Xr rtld 1 162.Sh HISTORY 163The 164.Nm libmap 165mechanism first appeared in 166.Fx 5.1 . 167.Sh AUTHORS 168This manual page was written by 169.An Matthew N. Dodd Aq Mt winter@jurai.net 170and extensively rewritten by 171.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . 172