share/man/man5/libmap.conf.5

   1 .\" Copyright (c) 2003 Matthew N. Dodd <winter@jurai.net>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd April 28, 2012
  28 .Dt LIBMAP.CONF 5
  29 .Os
  30 .Sh NAME
  31 .Nm libmap.conf
  32 .Nd "configuration file for dynamic object dependency mapping"
  33 .Sh DESCRIPTION
  34 The
  35 .Nm libmap
  36 functionality of
  37 .Xr ld-elf.so.1 1
  38 allows dynamic object dependencies to be mapped to arbitrary
  39 names.
  40 .Pp
  41 The configuration file consists of two whitespace separated columns; the
  42 left hand side containing the mapping candidate and the right hand
  43 side containing the mapping.
  44 Dependencies are matched against candidates and replaced with the mappings.
  45 .Pp
  46 Two special directives are available:
  47 .Bl -tag -width indent
  48 .It Cm include Ar file
  49 Parse the contents of
  50 .Ar file
  51 before continuing with the current file.
  52 .It Cm includedir Ar dir
  53 Parse the contents of every file in
  54 .Ar dir
  55 that ends in
  56 .Pa .conf
  57 before continuing with the current file.
  58 .El
  59 .Pp
  60 Any file or directory encountered while processing
  61 .Cm include
  62 or
  63 .Cm includedir
  64 directives will be parsed exactly once, even if it is encountered
  65 multiple times.
  66 .Pp
  67 Constrained mappings may be specified by enclosing the name of the
  68 executable or library in brackets.
  69 All mappings following a constraint will only be evaluated for that constraint.
  70 Constraints can be one of three types:
  71 .Bl -tag -width indent
  72 .It Exact
  73 The constraint is matched literally so that only an executable with an
  74 identical fully qualified pathname will match the constraint.
  75 This means that the executable
  76 .Pa /usr/bin/foo
  77 will not match a constraint for
  78 .Pa /usr/bin/./foo
  79 and vice-versa.
  80 This is the default constraint type.
  81 .It Basename
  82 A constraint with no path is matched against the basename of the
  83 executable.
  84 .Pa foo
  85 will match
  86 .Pa /bin/foo ,
  87 .Pa /usr/local/sbin/foo ,
  88 or any other executable named
  89 .Pa foo ,
  90 no matter what its path is.
  91 .It Directory
  92 A constraint with a trailing slash is prefix-matched against the full
  93 pathname of the executable.
  94 .Pa /usr/bin/
  95 will match any executable with a path starting with /usr/bin.
  96 .El
  97 .Pp
  98 Note that the executable path matched against is the
  99 .Fa path
 100 parameter in an
 101 .Fn exec*
 102 function call.
 103 The Directory or Exact constraints can only match when the executable
 104 is called with a full pathname.
 105 Most programs executed from a shell are run without a full path, via
 106 .Fn exec*p ,
 107 so the Basename constraint type is the most useful.
 108 .Pp
 109 WARNING!
 110 Constrained mappings must never appear first in the configuration file.
 111 While there is a way to specify the
 112 .Dq default
 113 constraint, its use is not recommended.
 114 .Pp
 115 The most common use at the date of writing is for allowing multiple
 116 .Tn POSIX
 117 threading libraries to be used on a system without relinking or
 118 changing symlinks.
 119 .Pp
 120 On 64-bit architectures that provide 32-bit runtime support,
 121 the libmap mechanism is available for 32-bit binaries too.
 122 The mappings has to be written into separate configuration file
 123 .Pa /etc/libmap32.conf .
 124 Currently only supported on amd64.
 125 .Pp
 126 This mechanism has also been used to create shims to allow Linux
 127 shared libraries to be dynamically loaded into
 128 .Fx
 129 binaries.
 130 In this case, an Exact constraint is used for the Linux shared library,
 131 mapping libraries it depends on to a wrapper.
 132 The wrapper then defines any needed symbols for the Linux shared library
 133 and relies on its libraries not being mapped to provide actual
 134 implementations.
 135 It appears that only libraries loaded via
 136 .Xr dlopen 3
 137 will work correctly.
 138 The symbol version information in shared libraries is checked at
 139 link time, but at run time the version information is currently
 140 ignored.
 141 .Sh FILES
 142 .Bl -tag -width ".Pa /etc/libmap32.conf" -compact
 143 .It Pa /etc/libmap.conf
 144 The libmap configuration file.
 145 .It Pa /etc/libmap32.conf
 146 The libmap configuration file for 32-bit binaries on 64-bit system.
 147 .El
 148 .Sh EXAMPLES
 149 .Bd -literal
 150 # /etc/libmap.conf
 151 #
 152 # candidate             mapping
 153 #
 154 libc_r.so.6             libpthread.so.2 # Everything that uses 'libc_r'
 155 libc_r.so               libpthread.so   # now uses 'libpthread'
 156
 157 [/tmp/mplayer]          # Test version of mplayer uses libc_r
 158 libpthread.so.2         libc_r.so.6
 159 libpthread.so           libc_r.so
 160
 161 [/usr/local/jdk1.4.1/]  # All Java 1.4.1 programs use libthr
 162                         # This works because "javavms" executes
 163                         # programs with the full pathname
 164 libpthread.so.2         libthr.so.2
 165 libpthread.so           libthr.so
 166
 167 # Glue for Linux-only EPSON printer .so to be loaded into cups, etc.
 168 [/usr/local/lib/pips/libsc80c.so]
 169 libc.so.6               pluginwrapper/pips.so
 170 libdl.so.2              pluginwrapper/pips.so
 171 .Ed
 172 .Sh SEE ALSO
 173 .Xr ldd 1 ,
 174 .Xr rtld 1
 175 .Sh HISTORY
 176 The
 177 .Nm
 178 manual page and
 179 .Nm libmap
 180 functionality first appeared in
 181 .Fx 5.1 .
 182 .Sh AUTHORS
 183 This manual page was written by
 184 .An Matthew N. Dodd Aq winter@jurai.net .