Case 01: Symbol Removal¶

Field	Value
Verdict	🔴 BREAKING
Category	Breaking
Platforms	Linux, macOS, Windows
Flags	ABI break, API break
Detected `ChangeKind`s	`func_removed`
Source files	browse on GitHub

Category: Symbol API | Verdict: 🔴 BREAKING

What breaks¶

Any downstream binary that dynamically links against helper() will fail at runtime with undefined symbol after upgrading to v2. Even if you no longer use helper(), removing it from the public .so is an ABI contract violation.

Why abidiff catches it¶

abidiff reports 1 Removed function and sets exit-bit 3 (value 8), giving exit code 12 (= 4 | 8): ABI change detected + breaking change.

Code diff¶

v1.c	v2.c
`int compute(int x) { return x * 2; }`	`int compute(int x) { return x * 2; }`
`int helper(int x) { return x + 1; }`	(removed)

Real Failure Demo¶

Severity: CRITICAL

Scenario: compile app against v1, swap in v2 .so without recompile.

# Build old library + app
gcc -shared -fPIC -g v1.c -o libfoo.so
gcc -g app.c -L. -lfoo -Wl,-rpath,. -o app
./app
# → compute(5) = 10
# → helper(5)  = 6

# Swap in new library (no recompile)
gcc -shared -fPIC -g v2.c -o libfoo.so
./app
# → ./app: symbol lookup error: ./app: undefined symbol: helper

Why CRITICAL: helper is removed from the dynamic symbol table in v2; the runtime linker cannot resolve the symbol and the process is killed immediately on startup.

Reproduce manually¶

gcc -shared -fPIC -g v1.c -o libfoo_v1.so
gcc -shared -fPIC -g v2.c -o libfoo_v2.so
abidw --out-file v1.xml libfoo_v1.so
abidw --out-file v2.xml libfoo_v2.so
abidiff v1.xml v2.xml
echo "exit: $?"   # → 12

How to fix¶

Never remove a public symbol in a minor/patch release. Deprecate with __attribute__((deprecated("use compute() instead"))) and only remove on the next SONAME bump (major version).

Real-world example¶

Common in C libraries during "API cleanup" refactors — OpenSSL 1.1.0 removed several low-level functions that were technically public, forcing all downstream packages to patch at once.