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.1 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 .