Application binary interface

Also known as: ABI

On this page 8

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.

ComponentWhat it definesTypical failure when mismatched
Calling conventionWhich registers or stack slots carry arguments and return valuesWrong arguments, corrupted stack
Data type sizes and alignmentWidth of int, long and pointers; padding of structuresMisread fields, crashes on access
System call interfaceSyscall numbers, argument registers, trap instructionInvalid syscall or wrong operation
Executable and object formatELF, PE/COFF or Mach-O layout, sections, relocationsLoader refuses the file
Name manglingHow C++ symbols are encoded in the symbol tableUnresolved symbols at link or load time
Exception and unwinding modelHow stack frames are unwound during exceptionsProcess aborts during error handling
Thread-local storage modelHow per-thread variables are locatedWrong data shared across threads
Core components of an application binary interface

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.

AspectAPIABI
LevelSource codeCompiled machine code
ConsumerProgrammer and compilerLinker, loader and running binaries
Example change that breaks itRenaming a functionAdding a field to a public struct
Fix after a breakEdit the source codeRecompile every dependent binary
Visibility of breakageCompile errorOften runtime crash or corruption
Comparison of API and ABI contracts

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 systemStable boundaryUnstable layerConsequence
WindowsDocumented Win32 DLL exportsRaw NT system call numbersVery long backward compatibility
LinuxKernel syscall interfaceInternal kernel modules, some user librariesStatic binaries run for decades
macOSlibSystem and system frameworksDirect system callsArchitecture transitions handled by Rosetta
FreeBSDSyscalls with compat layers per major releaseKernel module interfaceOld binaries need compat packages
Stable ABI boundaries in desktop operating systems

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.

SituationTypical approachExample
Same CPU, different OS interfaceCompatibility layer translating callsWine, Proton, Linux emulation in FreeBSD
Different CPU instruction setBinary translation or emulationRosetta 2, QEMU user mode
Same OS, older library ABIBundled or versioned librariesglibc symbol versions, side-by-side assemblies
Same OS, 32-bit binary on 64-bit hostMultilib and kernel compat pathWoW64, ia32 emulation
Strategies for running binaries with a foreign ABI

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.