---
name: "libmap.conf"
section: "5"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/libmap.conf"
---

# libmap.conf(5)

configuration file for dynamic object dependency mapping

## NAME

**libmap.conf** – configuration file for dynamic object dependency mapping

## DESCRIPTION

The **libmap** functionality of [ld-elf.so.1(1)](/ld-elf.so.1/1.md) allows dynamic object dependencies to be mapped to arbitrary names.

Each line in */etc/libmap.conf* can have one of five forms:

- *origin* *target*

  Whenever a dependency on *origin* is encountered while loading a dynamic object, use *target* instead of searching for *origin* in the normal library search paths.

- *path1* *path2*

  When iterating through a library search path, replace any element that matches *path1* exactly with *path2*.

- \[*constraint*\]

  Apply *constraint* to all subsequent mappings until the next constraint line or the end of the file. See the Constraints section for details.

- **include** *file*

  Parse the contents of *file* before continuing with the current file. Nesting depth is limited only by available memory, but each file encountered is processed only once, and loops are silently ignored.

- **includedir** *dir*

  Recurse through *dir* and parse the contents of any file that ends in *.conf* before continuing with the current file. Nesting depth is limited only by available memory, but each directory or file encountered is processed only once, and loops are silently ignored.

### Constraints

Constrained mappings only apply when processing binaries or libraries that satisfy the constraint. There are three types of constraints:

- Exact

  The constraint is matched literally so that only an executable with an identical fully qualified pathname will satisfy the constraint. This means that the executable */usr/bin/foo* will not satisfy the constraint \[*/usr/bin/./foo*\], and vice-versa. This is the default constraint type.

- Basename

  A constraint with no path is matched against the basename of the executable. For instance, the constraint \[*foo*\] will match */bin/foo*, */usr/local/sbin/foo*, or any other executable named *foo*, no matter what directory it is in.

- Directory

  A constraint with a trailing slash is satisfied if the full pathname begins with the constraint string. For instance, the constraint \[*/usr/bin/*\] will match any executable with a path starting with */usr/bin/*.

Note that the constraints are matched against the path that was passed as the first argument to whichever [exec(3)](/exec/3.md) function was used to execute the binary in question. Most programs executed from a shell are run without a full path, via [execvp(3)](/execvp/3.md) or similar, so the basename constraint type is the most useful.

WARNING! Constraints apply to all mappings until the next constraint or the end of the file. Hence, unconstrained mappings must be placed at the top of the file.

### ABI compatibility

On 64-bit architectures that provide 32-bit binary compatibility, the mappings in */etc/libmap.conf* apply only to 64-bit binaries. Mappings for 32-bit binaries must be placed in */etc/libmap32.conf*.

## FILES

- */etc/libmap.conf*

  The libmap configuration file.

- */etc/libmap32.conf*

  The libmap configuration file for 32-bit binaries on 64-bit system.

## EXAMPLES

```
#
# origin		target
#
libc_r.so.6		libpthread.so.2	# Everything that uses 'libc_r'
libc_r.so		libpthread.so	# now uses 'libpthread'
[/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" executes
			# 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)](/ldd/1.md), [rtld(1)](/rtld/1.md)

## HISTORY

The **libmap** mechanism first appeared in FreeBSD 5.1.

## AUTHORS

This manual page was written by Matthew N. Dodd ⟨*winter@jurai.net*⟩ and extensively rewritten by Dag-Erling Smørgrav ⟨*des@FreeBSD.org*⟩.