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: head/share/man/man5/libmap.conf.5 157178 2006-03-27 14:37:54Z pav $
  26 .\"
  27 .Dd February 20, 2011
  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 This mechanism has also been used to create shims to allow Linux
 100 shared libraries to be dynamically loaded into
 101 .Fx
 102 binaries.
 103 In this case, an Exact constraint is used for the Linux shared library,
 104 mapping libraries it depends on to a wrapper.
 105 The wrapper then defines any needed symbols for the Linux shared library
 106 and relies on its libraries not being mapped to provide actual
 107 implementations.
 108 It appears that only libraries loaded via
 109 .Xr dlopen 3
 110 will work correctly.
 111 The symbol version information in shared libraries is checked at
 112 link time, but at run time the version information is currently
 113 ignored.
 114 .Sh FILES
 115 .Bl -tag -width ".Pa /etc/libmap.conf" -compact
 116 .It Pa /etc/libmap.conf
 117 The libmap configuration file.
 118 .El
 119 .Sh EXAMPLES
 120 .Bd -literal
 121 # /etc/libmap.conf
 122 #
 123 # candidate             mapping
 124 #
 125 libc_r.so.6             libpthread.so.2 # Everything that uses 'libc_r'
 126 libc_r.so               libpthread.so   # now uses 'libpthread'
 127
 128 [/tmp/mplayer]          # Test version of mplayer uses libc_r
 129 libpthread.so.2         libc_r.so.6
 130 libpthread.so           libc_r.so
 131
 132 [/usr/local/jdk1.4.1/]  # All Java 1.4.1 programs use libthr
 133                         # This works because "javavms" executes
 134                         # programs with the full pathname
 135 libpthread.so.2         libthr.so.2
 136 libpthread.so           libthr.so
 137
 138 # Glue for Linux-only EPSON printer .so to be loaded into cups, etc.
 139 [/usr/local/lib/pips/libsc80c.so]
 140 libc.so.6               pluginwrapper/pips.so
 141 libdl.so.2              pluginwrapper/pips.so
 142 .Ed
 143 .Sh SEE ALSO
 144 .Xr ldd 1 ,
 145 .Xr rtld 1
 146 .Sh HISTORY
 147 The
 148 .Nm
 149 manual page and
 150 .Nm libmap
 151 functionality first appeared in
 152 .Fx 5.1 .
 153 .Sh AUTHORS
 154 This manual page was written by
 155 .An Matthew N. Dodd Aq winter@jurai.net .