LIBMAP.CONF(5)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

🎀 LIBMAP.CONF(5) 🎀

okay bestie, so this is the manual page for LIBMAP.CONF(5) — File Formats Manual energy, but make it cute. It's the config file for dynamic object dependency mapping, and honestly? It's giving "small file, huge power." Let's get into it 💅

✨ NAME ✨

libmap.conf — the configuration file for dynamic object dependency mapping. That's the whole vibe. Short, iconic, to the point 🫶

🌸 DESCRIPTION 🌸

So the libmap functionality of ld-elf.so.1(1) lets you map dynamic object dependencies to arbitrary names. Like, you say "hey when something asks for THIS, give them THAT instead" and the loader is like "say less." Slay.

Each line in /etc/libmap.conf can have one of five forms. Five! Not four, not six. Five. Let's go one by one ⭐

  • origin target — whenever a dependency on origin comes up while loading a dynamic object, use target instead of going looking for origin in the normal library search paths. No searching, no scavenger hunt, just vibes.
  • path1 path2 — when it's iterating through a library search path, replace any element that matches path1 exactly with path2. Exact match only, bestie — no fuzzy matching, no "close enough."
  • [constraint] — applies that constraint to all the mappings that come after it, all the way until the next constraint line or the end of the file. More on this in the Constraints section below 👇
  • 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. So you can't trap it in an infinite loop — it just shrugs and moves on 💀
  • includedir dir — recurse through dir and parse the contents of any file that ends in .conf before continuing with the current file. Again: nesting depth is limited only by available memory, each directory or file encountered is processed only once, and loops are silently ignored. Same energy, directory edition.

👑 Constraints 👑

Constrained mappings only apply when processing binaries or libraries that satisfy the constraint. So like, the mapping only kicks in for the cool kids who match. There are three types of constraints:

🧚 Exact

The constraint is matched literally, so only an executable with an identical fully qualified pathname will satisfy it. That means the executable /usr/bin/foo will not satisfy the constraint [/usr/bin/./foo], and vice-versa. Not even a little bit. Same file, different string, different vibe. 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's in. Iconic, honestly — it just doesn't care about the neighborhood.

🌈 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/. Prefix match supremacy ✨

Heads up bestie: the constraints are matched against the path that was passed as the first argument to whichever exec(3) function was used to execute the binary in question. Most programs executed from a shell are run without a full path, via execvp(3) or similar, so the basename constraint type is the most useful one. iykyk.
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. Like, this is not optional. Put them at the top. Please. 🙈

🔥 ABI compatibility 🔥

On 64-bit architectures that provide 32-bit binary compatibility, the mappings in /etc/libmap.conf apply only to 64-bit binaries. If you need mappings for 32-bit binaries, those go in /etc/libmap32.conf. Two files, two lanes, no crossing over 🫶

🍓 FILES 🍓

  • /etc/libmap.conf — the libmap configuration file. The main character.
  • /etc/libmap32.conf — the libmap configuration file for 32-bit binaries on a 64-bit system. The understudy.

💖 EXAMPLES 💖

Strap in, this is the good part:

#
# 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

Look at that formatting. Chef's kiss. The comments are literally in the example, keep them 💅

👀 SEE ALSO 👀

Go read those too, bestie. Knowledge is free 💜

⭐ HISTORY ⭐

The libmap mechanism first appeared in FreeBSD 5.1. A true OG. It's been serving looks since way back 🌸

🥺 AUTHORS 🥺

This manual page was written by Matthew N. Dodd <winter@jurai.net> and extensively rewritten by Dag-Erling Smørgrav <des@FreeBSD.org>. Thank you for your service, kings 👑🫶

okay that's the whole page!! and before you close the tab — this one came from the Debian crew, dated September 16, 2013, filed under LIBMAP.CONF(5). Go forth and map your dependencies, bestie, you've got this 💖✨🎀

📦 where this page comes from