libmap.conf(5)

NAME

libmap.conf - configuration file for dynamic object depen

dency mapping

DESCRIPTION

The libmap functionality of ld-elf.so.1(1) allows dynamic

object dependencies to be mapped to arbitrary names.

The configuration file consists of two whitespace separated

columns; the
left hand side containing the mapping candidate and the

right hand side
containing the mapping. Dependencies are matched against

candidates and
replaced with the mappings.

Constrained mappings may be specified by enclosing the name

of the executable or library in brackets. All mappings following a

constraint will
only be evaluated for that constraint. Constraints can be

one of three
types:

Exact The constraint is matched literally so that only an

executable

with an identical fully qualified pathname will

match the constraint. This means that the executable

/usr/bin/foo will not
match a constraint for /usr/bin/./foo and vice-ver

sa. This is
the default constraint type.

Basename

A constraint with no path is matched against the

basename of the
executable. foo will match /bin/foo,

/usr/local/sbin/foo, or any
other executable named foo, no matter what its path

is.

Directory

A constraint with a trailing slash is prefix-matched

against the
full pathname of the executable. /usr/bin/ will

match any executable with a path starting with /usr/bin.

Note that the executable path matched against is the path

parameter in an
exec*() function call. The Directory or Exact constraints

can only match
when the executable is called with a full pathname. Most

programs executed from a shell are run without a full path, via

exec*p(), so the
Basename constraint type is the most useful.

WARNING! Constrained mappings must never appear first in

the configuration file. While there is a way to specify the ``default''

constraint,
its use is not recommended.

The most common use at the date of writing is for allowing

multiple POSIX
threading libraries to be used on a system without relinking

or changing
symlinks.

This mechanism has also been used to create shims to allow

Linux shared
libraries to be dynamically loaded into FreeBSD binaries.

In this case,
an Exact constraint is used for the Linux shared library,

mapping
libraries it depends on to a wrapper. The wrapper then de

fines any
needed symbols for the Linux shared library and relies on

its libraries
not being mapped to provide actual implementations. It ap

pears that only
libraries loaded via dlopen(3) will work correctly. The

symbol version
information in shared libraries is checked at link time, but

at run time
the version information is currently ignored.

FILES

/etc/libmap.conf The libmap configuration file.

EXAMPLES

# /etc/libmap.conf
#
# candidate mapping
#
libc_r.so.6 libpthread.so.2 # Everything that

uses 'libc_r'
libc_r.so libpthread.so # now uses

[/tmp/mplayer] # Test version of mplayer uses

libc_r
libpthread.so.2 libc_r.so.6
libpthread.so libc_r.so

[/usr/local/jdk1.4.1/] # All Java 1.4.1 programs use libthr

# This works because "javavms" exe

cutes
# programs with the full pathname

libpthread.so.2 libthr.so.2
libpthread.so libthr.so

# Glue for Linux-only EPSON printer .so to be loaded into

cups, etc.
[/usr/local/lib/pips/libsc80c.so]
libc.so.6 pluginwrapper/pips.so
libdl.so.2 pluginwrapper/pips.so

SEE ALSO

ldd(1), rtld(1)

HISTORY

The libmap.conf manual page and libmap functionality first

appeared in
FreeBSD 5.1.

AUTHORS

This manual page was written by Matthew N. Dodd <winter@ju

rai.net>.

BSD January 31, 2004

BSD