--- title: Translate a GNU version script into an illumos mapfile, or drop it on purpose; check with pvs and lari area: link impact: MEDIUM tags: [link, ld, mapfile, version-script, symbol-versioning, direct-binding, lari, pvs, porting, packaging] verified: 2026-11-04 --- # Translate a GNU version script into an illumos mapfile, or drop it on purpose; check with pvs and lari The illumos link-editor scopes and versions symbols with mapfiles (`ld -M`). It has no `--version-script`, so a Linux link line that passes one fails. Either drop the script, which leaves every symbol global and unversioned, or write a mapfile. Choose by asking whether anything needs the version names. **Antipattern** ```sh gcc -shared -o libfoo.so.1 *.o -Wl,--version-script,libfoo.map # ld: fatal: unrecognized option '--version-script' # sed every --version-script out of the build and never ask who needs the version names (libzfs needs zlib's) ``` **The Solnix way** ```sh # 1. no consumer needs the version names: drop the flag (the build team's shim: LDVERSCRIPT_STRIP=1 in scripts/oi-clib.sh, `ldVersionScriptFix` in packages.nix) # 2. a consumer needs them, or internals must stay hidden: rewrite the script as a version 2 mapfile cat > mapfile-vers <<'EOF' $mapfile_version 2 SYMBOL_VERSION FOO_1.0 { global: foo_open; foo_close; local: *; }; EOF gcc -shared -o libfoo.so.1 *.o -Wl,-h,libfoo.so.1 -Wl,-M,mapfile-vers -Wl,-z,defs -Wl,-B,direct pvs -dos libfoo.so.1 # each exported symbol with its version: foo_open and foo_close under FOO_1.0 lari -omv ./prog # draft a mapfile- in . for each unversioned object prog loads lari ./prog # symbols with more than one definition, and which definition gets the bindings # lari -s ./prog: also save the binding output (lari.dbg), which shows where each reference came from ``` Dropping is the build team's usual fix, harmless when nothing uses the version names. `-B direct` binds each reference to the object that defines it; pair it with `-z defs`. An object meant to interpose under direct binding links with `-z interpose`. lari tokens: `D` direct, `I` interposer, `N` no direct binding, `r` rejected. **The illumos way** (OpenIndiana, OmniOS, SmartOS) ```sh # illumos-gate: every library has common/mapfile-vers (read usr/src/lib/README.mapfiles first) # $mapfile_version 2 # SYMBOL_VERSION ILLUMOS_0.1 { global: ... } # SYMBOL_VERSION ILLUMOSprivate { global: ... local: *; }; lari -omv ./main && cat mapfile-foo.so # lari(1) Example 2 pvs -d /lib/libelf.so.1 # pvs(1) Example 1: SUNW_1.1 ``` Same link-editor, so the same mapfiles. Solnix builds zlib with OpenIndiana's symbol-version mapfile, because libzfs requires it. **The difference.** The link-editor is the same as upstream illumos. Solnix ports many Linux libraries, and the build team's usual fix strips `--version-script`, so those libraries export every symbol with no version. That matters once something depends on the versions: a program linked against a versioned library records the versions it uses, and ld.so.1 checks them at process start. With direct bindings, load order alone no longer decides which definition wins: in lari(1) Example 1, libX.so and libY.so each bind to their own `foo()`. **Check.** `pvs -dos libfoo.so.1` lists every symbol the Linux script exported, under its version names (`FOO_1.0` here), and no internal helper names. **Unverified** - The full mapfile version 2 grammar. ld(1) points to Chapter 9 of the Linker and Libraries Guide, which is not a source here; the example above follows the illumos Developer's Guide shape. - Version inheritance (GNU `FOO_1.1 { ... } FOO_1.0;`), wildcards in `global:`, and `extern "C++"` blocks: not checked in any source. - Whether `-M` takes a simple GNU script unchanged. lari(1) Example 2 writes the same `name { global: ...; local: *; };` shape for `-M`, but the build team calls the grammars incompatible; test with pvs. - Whether Solnix links with `-B direct` by default. illumos-domain.md says "direct bindings by default", and the wrapper code is not in the snapshot. - `LDVERSCRIPT_STRIP=1` and `ldVersionScriptFix` are named in the build team's docs; the code (scripts/oi-clib.sh, pkgs/illumos/packages.nix) is not in the snapshot. - How OmniOS and SmartOS handle GNU version scripts. No cited source says. **Sources** - [ld(1)](https://solnix.io/docs/man/ld.1) (illumos, CDDL), SYNOPSIS (no `--version-script`); -M mapfile; -h name / -soname; -B direct | -B nodirect; -z direct; -z defs; -z interpose (load-order interposition; explicit interposers under direct binding); -z guidance (Version 2 mapfile syntax) - [lari(1)](https://solnix.io/docs/man/lari.1) (illumos, CDDL), DESCRIPTION (generate interface definitions for `-M`); -m, -o, -v, -d mapdir (default: current directory), -i (default); tokens D, I, N, P, r; Interesting Information; Overhead Information; Examples 1 and 2 - [pvs(1)](https://solnix.io/docs/man/pvs.1) (illumos, CDDL), DESCRIPTION (version dependencies recorded at link time, validated at process initialization); -d, -o, -s; Example 1 - [gcc(1)](https://solnix.io/docs/man/gcc.1) (Solnix pkgs.solnix.gcc), -shared; -Wl,option - [compare: ld(1)](https://solnix.io/docs/man/compare/ld.1), script and mapfile control (no linker-script option) - [illumos Developer's Guide: Component Anatomy](https://illumos.org/books/dev/anatomy.html#mapfiles-public-interfaces-and-versioning) (PDL), Mapfiles, Public Interfaces, and Versioning; Headers, Source, Mapfiles, and Lint Libraries (`$mapfile_version 2`, `SYMBOL_VERSION`, `local: *`) - [.kiro/steering/illumos-domain.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/.kiro/steering/illumos-domain.md) (solnix 5a8e5ce), libc / linker / runtime (mapfiles v2 for versioning and scoping; direct bindings) - [docs/design-pkgsrc-patches.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/design-pkgsrc-patches.md) (solnix 5a8e5ce), Family 5 GNU linker `--version-script` (the ld error; incompatible grammar; drop it, symbols keep global scope) - [docs/design-nix-managed-base.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/design-nix-managed-base.md) (solnix 5a8e5ce), Everything on the target is built from source (zlib with OpenIndiana's symbol-version mapfile, which libzfs requires) - [docs/design-desktop-and-local-ai.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/design-desktop-and-local-ai.md) (solnix 5a8e5ce), G0 MILESTONE (sed every --version-script out of Makefile.am/.in)