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 January 31, 2004
  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 Constrained mappings may be specified by enclosing the name of the
  47 executable or library in brackets.
  48 All mappings following a constraint will only be evaluated for that constraint.
  49 Constraints can be one of three types:
  50 .Bl -tag -width indent
  51 .It Exact
  52 The constraint is matched literally so that only an executable with an
  53 identical fully qualified pathname will match the constraint.
  54 This means that the executable
  55 .Pa /usr/bin/foo
  56 will not match a constraint for
  57 .Pa /usr/bin/./foo
  58 and vice-versa.
  59 This is the default constraint type.
  60 .It Basename
  61 A constraint with no path is matched against the basename of the
  62 executable.
  63 .Pa foo
  64 will match
  65 .Pa /bin/foo ,
  66 .Pa /usr/local/sbin/foo ,
  67 or any other executable named
  68 .Pa foo ,
  69 no matter what its path is.
  70 .It Directory
  71 A constraint with a trailing slash is prefix-matched against the full
  72 pathname of the executable.
  73 .Pa /usr/bin/
  74 will match any executable with a path starting with /usr/bin.
  75 .El
  76 .Pp
  77 Note that the executable path matched against is the
  78 .Fa path
  79 parameter in an
  80 .Fn exec*
  81 function call.
  82 The Directory or Exact constraints can only match when the executable
  83 is called with a full pathname.
  84 Most programs executed from a shell are run without a full path, via
  85 .Fn exec*p ,
  86 so the Basename constraint type is the most useful.
  87 .Pp
  88 WARNING!
  89 Constrained mappings must never appear first in the configuration file.
  90 While there is a way to specify the
  91 .Dq default
  92 constraint, its use is not recommended.
  93 .Pp
  94 The most common use at the date of writing is for allowing multiple
  95 .Tn POSIX
  96 threading libraries to be used on a system without relinking or
  97 changing symlinks.
  98 .Pp
  99 On 64-bit architectures that provide 32-bit runtime support,
 100 the libmap mechanism is available for 32-bit binaries too.
 101 The mappings has to be written into separate configuration file
 102 .Pa /etc/libmap32.conf .
 103 Currently only supported on amd64.
 104 .Pp
 105 This mechanism has also been used to create shims to allow Linux
 106 shared libraries to be dynamically loaded into
 107 .Fx
 108 binaries.
 109 In this case, an Exact constraint is used for the Linux shared library,
 110 mapping libraries it depends on to a wrapper.
 111 The wrapper then defines any needed symbols for the Linux shared library
 112 and relies on its libraries not being mapped to provide actual
 113 implementations.
 114 It appears that only libraries loaded via
 115 .Xr dlopen 3
 116 will work correctly.
 117 The symbol version information in shared libraries is checked at
 118 link time, but at run time the version information is currently
 119 ignored.
 120 .Sh FILES
 121 .Bl -tag -width ".Pa /etc/libmap32.conf" -compact
 122 .It Pa /etc/libmap.conf
 123 The libmap configuration file.
 124 .It Pa /etc/libmap32.conf
 125 The libmap configuration file for 32-bit binaries on 64-bit system.
 126 .El
 127 .Sh EXAMPLES
 128 .Bd -literal
 129 # /etc/libmap.conf
 130 #
 131 # candidate             mapping
 132 #
 133 libc_r.so.6             libpthread.so.2 # Everything that uses 'libc_r'
 134 libc_r.so               libpthread.so   # now uses 'libpthread'
 135
 136 [/tmp/mplayer]          # Test version of mplayer uses libc_r
 137 libpthread.so.2         libc_r.so.6
 138 libpthread.so           libc_r.so
 139
 140 [/usr/local/jdk1.4.1/]  # All Java 1.4.1 programs use libthr
 141                         # This works because "javavms" executes
 142                         # programs with the full pathname
 143 libpthread.so.2         libthr.so.2
 144 libpthread.so           libthr.so
 145
 146 # Glue for Linux-only EPSON printer .so to be loaded into cups, etc.
 147 [/usr/local/lib/pips/libsc80c.so]
 148 libc.so.6               pluginwrapper/pips.so
 149 libdl.so.2              pluginwrapper/pips.so
 150 .Ed
 151 .Sh SEE ALSO
 152 .Xr ldd 1 ,
 153 .Xr rtld 1
 154 .Sh HISTORY
 155 The
 156 .Nm
 157 manual page and
 158 .Nm libmap
 159 functionality first appeared in
 160 .Fx 5.1 .
 161 .Sh AUTHORS
 162 This manual page was written by
 163 .An Matthew N. Dodd Aq winter@jurai.net .