Commit | Line | Data |
---|---|---|
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 | |
35 | The | |
36 | .Nm libmap | |
37 | functionality of | |
70839a95 | 38 | .Xr ld-elf.so.2 1 |
4e9c0f50 | 39 | allows dynamic object dependencies to be mapped to arbitrary names. |
fcf53d9b | 40 | .Pp |
4e9c0f50 JM |
41 | Each line in |
42 | .Pa /etc/libmap.conf | |
43 | can have one of five forms: | |
51b1ba8e | 44 | .Bl -tag -width indent |
4e9c0f50 JM |
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. | |
51b1ba8e JM |
67 | .It Cm include Ar file |
68 | Parse the contents of | |
69 | .Ar file | |
70 | before continuing with the current file. | |
4e9c0f50 JM |
71 | Nesting depth is limited only by available memory, but each file |
72 | encountered is processed only once, and loops are silently ignored. | |
51b1ba8e | 73 | .It Cm includedir Ar dir |
4e9c0f50 | 74 | Recurse through |
51b1ba8e | 75 | .Ar dir |
4e9c0f50 | 76 | and parse the contents of any file that ends in |
51b1ba8e JM |
77 | .Pa .conf |
78 | before continuing with the current file. | |
4e9c0f50 JM |
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. | |
51b1ba8e | 82 | .El |
4e9c0f50 JM |
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: | |
fcf53d9b JM |
87 | .Bl -tag -width indent |
88 | .It Exact | |
89 | The constraint is matched literally so that only an executable with an | |
4e9c0f50 | 90 | identical fully qualified pathname will satisfy the constraint. |
fcf53d9b JM |
91 | This means that the executable |
92 | .Pa /usr/bin/foo | |
4e9c0f50 JM |
93 | will not satisfy the constraint |
94 | .Bq Pa /usr/bin/./foo , | |
fcf53d9b JM |
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. | |
4e9c0f50 JM |
100 | For instance, the constraint |
101 | .Bq Pa foo | |
fcf53d9b JM |
102 | will match |
103 | .Pa /bin/foo , | |
104 | .Pa /usr/local/sbin/foo , | |
105 | or any other executable named | |
106 | .Pa foo , | |
4e9c0f50 | 107 | no matter what directory it is in. |
fcf53d9b | 108 | .It Directory |
4e9c0f50 JM |
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/ . | |
fcf53d9b JM |
115 | .El |
116 | .Pp | |
4e9c0f50 JM |
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. | |
fcf53d9b | 121 | Most programs executed from a shell are run without a full path, via |
4e9c0f50 JM |
122 | .Xr execvp 3 |
123 | or similar, so the basename constraint type is the most useful. | |
fcf53d9b | 124 | .Pp |
4e9c0f50 | 125 | .Bf -symbolic |
fcf53d9b | 126 | WARNING! |
4e9c0f50 JM |
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 | |
fcf53d9b JM |
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 | |
fcf53d9b | 138 | # |
4e9c0f50 | 139 | # candidate target |
fcf53d9b JM |
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 | |
fcf53d9b | 164 | .Nm libmap |
4e9c0f50 | 165 | mechanism first appeared in |
fcf53d9b JM |
166 | .Fx 5.1 . |
167 | .Sh AUTHORS | |
168 | This manual page was written by | |
4e9c0f50 JM |
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 . |