An application binary interface (ABI) is the low-level contract that defines how compiled machine code interacts with an operating system, with libraries and with other compiled modules. Where an API describes functions at the level of source code, an ABI fixes the binary details: how arguments travel in registers, how data structures are laid out in memory, how system calls are invoked and how executable files are formatted.
In operating systems, the ABI is the foundation of OS compatibility. A program built years ago keeps running on a new release only if the system preserves the ABI it was compiled against. When the ABI changes, the program must be recompiled, translated or emulated, which is why vendors treat ABI stability as one of their most expensive long-term commitments.
What an application binary interface specifies
An ABI specifies every convention that two pieces of compiled code must share to call each other correctly. Compilers, linkers, loaders and the kernel all implement parts of it, so a mismatch in any single element can cause crashes, silent data corruption or load failures rather than a clean error message.
The following table lists the main components of an ABI and what each one governs in practice.
| Component | What it defines | Typical failure when mismatched |
|---|---|---|
| Calling convention | Which registers or stack slots carry arguments and return values | Wrong arguments, corrupted stack |
| Data type sizes and alignment | Width of int, long and pointers; padding of structures | Misread fields, crashes on access |
| System call interface | Syscall numbers, argument registers, trap instruction | Invalid syscall or wrong operation |
| Executable and object format | ELF, PE/COFF or Mach-O layout, sections, relocations | Loader refuses the file |
| Name mangling | How C++ symbols are encoded in the symbol table | Unresolved symbols at link or load time |
| Exception and unwinding model | How stack frames are unwound during exceptions | Process aborts during error handling |
| Thread-local storage model | How per-thread variables are located | Wrong data shared across threads |
Several of these rules come from processor-specific supplements, such as the System V AMD64 psABI used by Linux, BSD and macOS on x86-64, or the Microsoft x64 calling convention used by Windows. The operating system then adds its own layer: kernel interfaces, library versions and loader behavior.
ABI versus API
An API is a source-level promise, while an ABI is a binary-level promise. A library can keep its API identical and still break its ABI, for example by adding a field to a public structure, reordering virtual functions in a C++ class or changing an enumeration’s underlying type. Existing binaries then misinterpret memory even though the source code would still compile.
The comparison below shows how the two contracts differ in scope and in the cost of breaking them.
| Aspect | API | ABI |
|---|---|---|
| Level | Source code | Compiled machine code |
| Consumer | Programmer and compiler | Linker, loader and running binaries |
| Example change that breaks it | Renaming a function | Adding a field to a public struct |
| Fix after a break | Edit the source code | Recompile every dependent binary |
| Visibility of breakage | Compile error | Often runtime crash or corruption |
Because ABI breaks are often invisible until runtime, library maintainers use techniques such as opaque pointers, the pimpl idiom, symbol versioning in glibc and tools that compare exported symbols between releases.
How operating systems keep ABIs stable
Operating systems differ sharply in which layer they treat as the stable boundary. Windows promises stability at the level of documented DLL exports such as kernel32.dll, while raw system call numbers change between builds, which is why programs from the Windows XP era often still run today. Linux treats the kernel system call ABI as nearly sacred, but user-space library ABIs vary between distributions.
The table summarizes where the main desktop systems draw the compatibility line.
| Operating system | Stable boundary | Unstable layer | Consequence |
|---|---|---|---|
| Windows | Documented Win32 DLL exports | Raw NT system call numbers | Very long backward compatibility |
| Linux | Kernel syscall interface | Internal kernel modules, some user libraries | Static binaries run for decades |
| macOS | libSystem and system frameworks | Direct system calls | Architecture transitions handled by Rosetta |
| FreeBSD | Syscalls with compat layers per major release | Kernel module interface | Old binaries need compat packages |
Linux also illustrates a common distinction: the kernel module ABI is intentionally unstable, so out-of-tree drivers must be rebuilt for each kernel version, while the user-space ABI is preserved. This split explains much of the friction around proprietary graphics drivers.
ABI variants on the same hardware
One processor architecture can host several incompatible ABIs, and the operating system must know which one a binary expects. On x86-64 Linux, the native LP64 ABI uses 64-bit pointers, the legacy i386 ABI serves 32-bit applications, and the rarely used x32 ABI combines 64-bit registers with 32-bit pointers. On 32-bit ARM, the soft-float and hard-float variants pass floating-point arguments differently and cannot be mixed in one process.
A 64-bit operating system that runs 32-bit programs therefore ships a second set of libraries and a translation path in the kernel, such as WoW64 on Windows or the compat syscall table on Linux. Removing that layer, as macOS Catalina did in 2019, instantly ends support for every 32-bit binary.
When ABI differences require translation
When a binary’s ABI differs from the host, the system has several options, each with a different cost in performance and fidelity. Choosing among them depends on whether the instruction set, the operating system interface or only the library versions differ.
| Situation | Typical approach | Example |
|---|---|---|
| Same CPU, different OS interface | Compatibility layer translating calls | Wine, Proton, Linux emulation in FreeBSD |
| Different CPU instruction set | Binary translation or emulation | Rosetta 2, QEMU user mode |
| Same OS, older library ABI | Bundled or versioned libraries | glibc symbol versions, side-by-side assemblies |
| Same OS, 32-bit binary on 64-bit host | Multilib and kernel compat path | WoW64, ia32 emulation |
Compatibility layers such as Wine reimplement the Windows ABI on top of Linux without emulating the processor, so performance can approach native speed. Binary translation must also convert instructions, which adds overhead and complexity around memory ordering.
Common ABI mistakes and misconceptions
- Assuming API compatibility implies ABI compatibility. A recompiled program may work while old binaries crash against the same new library.
- Mixing compilers or runtime versions. C++ objects built with different standard library versions can disagree on class layout, especially std::string.
- Linking against a newer glibc than the target system provides. The binary fails to start with a missing symbol version error.
- Treating the C ABI as universal. Only the C calling convention is broadly shared; C++, Rust and Swift expose stable ABIs only under specific rules.
- Ignoring structure packing. Compiler pragmas that change alignment silently break any binary that shares those structures.
In plain words
Think of an ABI as the shared plug and socket shape between a program and the system it runs on. Source code is like a design drawing; once it is built into a finished program, the program can only plug into a system whose socket has exactly the same shape.
If the operating system keeps that socket unchanged, old programs keep working. If the shape changes, the program needs an adapter, such as a compatibility layer or emulator, or it has to be rebuilt. A stable ABI is why software from many years ago can still run on a modern computer.
A real-world example
A small engineering firm relies on a measurement tool compiled for 32-bit Linux in 2012, and the vendor no longer exists. When the firm upgrades its workstations to a current 64-bit distribution, the tool refuses to start with a loader error, because the system no longer installs the i386 multilib libraries by default.
The administrator installs the 32-bit runtime packages, which restores the libraries the binary expects, while the kernel’s ia32 compatibility path handles its system calls. The tool runs again unchanged. For long-term safety, the team also packages it in a container with its original libraries pinned, so a future distribution change cannot break the binary contract the program depends on.