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