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