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: share/man/man5/libmap.conf.5 234851 2012-04-30 bapt $
  26 .\"
  27 .Dd May 3, 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 This mechanism has also been used to create shims to allow Linux
 121 shared libraries to be dynamically loaded into
 122 .Fx
 123 binaries.
 124 In this case, an Exact constraint is used for the Linux shared library,
 125 mapping libraries it depends on to a wrapper.
 126 The wrapper then defines any needed symbols for the Linux shared library
 127 and relies on its libraries not being mapped to provide actual
 128 implementations.
 129 It appears that only libraries loaded via
 130 .Xr dlopen 3
 131 will work correctly.
 132 The symbol version information in shared libraries is checked at
 133 link time, but at run time the version information is currently
 134 ignored.
 135 .Sh FILES
 136 .Bl -tag -width ".Pa /etc/libmap.conf" -compact
 137 .It Pa /etc/libmap.conf
 138 The libmap configuration file.
 139 .El
 140 .Sh EXAMPLES
 141 .Bd -literal
 142 # /etc/libmap.conf
 143 #
 144 # candidate             mapping
 145 #
 146 libc_r.so.6             libpthread.so.2 # Everything that uses 'libc_r'
 147 libc_r.so               libpthread.so   # now uses 'libpthread'
 148
 149 [/tmp/mplayer]          # Test version of mplayer uses libc_r
 150 libpthread.so.2         libc_r.so.6
 151 libpthread.so           libc_r.so
 152
 153 [/usr/local/jdk1.4.1/]  # All Java 1.4.1 programs use libthr
 154                         # This works because "javavms" executes
 155                         # programs with the full pathname
 156 libpthread.so.2         libthr.so.2
 157 libpthread.so           libthr.so
 158
 159 # Glue for Linux-only EPSON printer .so to be loaded into cups, etc.
 160 [/usr/local/lib/pips/libsc80c.so]
 161 libc.so.6               pluginwrapper/pips.so
 162 libdl.so.2              pluginwrapper/pips.so
 163 .Ed
 164 .Sh SEE ALSO
 165 .Xr ldd 1 ,
 166 .Xr rtld 1
 167 .Sh HISTORY
 168 The
 169 .Nm
 170 manual page and
 171 .Nm libmap
 172 functionality first appeared in
 173 .Fx 5.1 .
 174 .Sh AUTHORS
 175 This manual page was written by
 176 .An Matthew N. Dodd Aq winter@jurai.net .