i386 removal, part 71/x: Remove legacy FreeBSD brand.
[dragonfly.git] / share / man / man5 / libmap.conf.5
CommitLineData
fcf53d9b 1.\" Copyright (c) 2003 Matthew N. Dodd <winter@jurai.net>
4e9c0f50 2.\" Copyright (c) 2013 Dag-Erling Smørgrav
fcf53d9b
JM
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.\"
4e9c0f50 26.\" $FreeBSD: head/share/man/man5/libmap.conf.5 255765 2013-09-21 21:03:52Z des $
fcf53d9b 27.\"
4e9c0f50 28.Dd September 16, 2013
fcf53d9b
JM
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
70839a95 38.Xr ld-elf.so.2 1
4e9c0f50 39allows dynamic object dependencies to be mapped to arbitrary names.
fcf53d9b 40.Pp
4e9c0f50
JM
41Each line in
42.Pa /etc/libmap.conf
43can have one of five forms:
51b1ba8e 44.Bl -tag -width indent
4e9c0f50
JM
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.
51b1ba8e
JM
67.It Cm include Ar file
68Parse the contents of
69.Ar file
70before continuing with the current file.
4e9c0f50
JM
71Nesting depth is limited only by available memory, but each file
72encountered is processed only once, and loops are silently ignored.
51b1ba8e 73.It Cm includedir Ar dir
4e9c0f50 74Recurse through
51b1ba8e 75.Ar dir
4e9c0f50 76and parse the contents of any file that ends in
51b1ba8e
JM
77.Pa .conf
78before continuing with the current file.
4e9c0f50
JM
79Nesting depth is limited only by available memory, but each directory
80or file encountered is processed only once, and loops are silently
81ignored.
51b1ba8e 82.El
4e9c0f50
JM
83.Ss Constraints
84Constrained mappings only apply when processing binaries or libraries
85that satisfy the constraint.
86There are three types of constraints:
fcf53d9b
JM
87.Bl -tag -width indent
88.It Exact
89The constraint is matched literally so that only an executable with an
4e9c0f50 90identical fully qualified pathname will satisfy the constraint.
fcf53d9b
JM
91This means that the executable
92.Pa /usr/bin/foo
4e9c0f50
JM
93will not satisfy the constraint
94.Bq Pa /usr/bin/./foo ,
fcf53d9b
JM
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.
4e9c0f50
JM
100For instance, the constraint
101.Bq Pa foo
fcf53d9b
JM
102will match
103.Pa /bin/foo ,
104.Pa /usr/local/sbin/foo ,
105or any other executable named
106.Pa foo ,
4e9c0f50 107no matter what directory it is in.
fcf53d9b 108.It Directory
4e9c0f50
JM
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/ .
fcf53d9b
JM
115.El
116.Pp
4e9c0f50
JM
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.
fcf53d9b 121Most programs executed from a shell are run without a full path, via
4e9c0f50
JM
122.Xr execvp 3
123or similar, so the basename constraint type is the most useful.
fcf53d9b 124.Pp
4e9c0f50 125.Bf -symbolic
fcf53d9b 126WARNING!
4e9c0f50
JM
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
fcf53d9b
JM
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
fcf53d9b 138#
4e9c0f50 139# candidate target
fcf53d9b
JM
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
fcf53d9b 164.Nm libmap
4e9c0f50 165mechanism first appeared in
fcf53d9b
JM
166.Fx 5.1 .
167.Sh AUTHORS
168This manual page was written by
4e9c0f50
JM
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 .