Day 66: ABI Compatibility in C Language

In the previous lecture, we analyzed the issues and best practices of dynamic loading libraries (such as dlopen), including the dynamic loading process, common pitfalls, and safe coding paradigms.

1. Step-by-step Explanation of the Theme Principles and Details

ABI (Application Binary Interface) determines how different binary modules (such as executable files, dynamic libraries, and static libraries) interact with each other. It specifies low-level details such as function calls, parameter passing, stack frame layout, memory layout of structures/unions, name mangling, data type sizes and alignment, return value handling, and global variable access.

ABI compatibility refers to whether different modules can correctly cooperate at the binary level after compilation (for example, between the main program and .so/.dll libraries, or between plugins and the main program). ABI incompatibility can lead to crashes, data corruption, and undefined behavior, even if the source-level signatures are consistent.

Common ABI-related content includes:

• • Basic data type sizes and alignment (int/long/float/struct…)
• • Endianness
• • Calling conventions (cdecl/stdcall/fastcall, etc., affecting parameter passing and stack cleanup)
• • Layout of structures/unions/bit-fields
• • Name mangling (especially significant in C++)
• • CRT (C Runtime) dependencies

ABI compatibility is generally stricter than API compatibility.

2. Explanation of Typical Traps/Defects in C Language and Analysis of Causes

2.1 ABI Incompatibility Caused by Cross-Compiler/Different Compiler Versions

• • Different compilers (such as GCC and Clang, VC++ and GCC) may have different default data alignment, calling conventions, structure padding, etc.;
• • The ABI may also change between different versions of the same compiler (for example, ABI changes caused by glibc updates).

2.2 Changes in Structure Layout

• • Different field order, data types, and compiler alignment options (such as <span>#pragma pack</span>) can lead to incompatible memory layouts and sizes.

2.3 C++ Name Mangling

• • C++ enables name mangling by default, which can cause functions to be undetectable using C methods like <span>dlsym</span>, or lead to linking failures.

2.4 Inconsistent Calling Conventions

• • Mixing <span>__cdecl</span>, <span>__stdcall</span>, and <span>__fastcall</span> on Windows can lead to stack corruption.

2.5 Inconsistent CRT (C Runtime)

• • Different compilation options (MD/MT/MSVCRT) or mixing Debug/Release on Windows can lead to incompatibilities in global variables, memory allocation, and I/O.

2.6 Mixing 32-bit and 64-bit

• • Different lengths of types like pointers and long can lead to complete ABI incompatibility.

3. Avoidance Methods and Best Design Practices

• • All related modules should use the same compiler, the same version, and completely consistent compilation parameters (such as <span>-m32/-m64</span>, <span>-fPIC</span>, optimization options, etc.);
• • When using structures/unions for ABI interfaces, avoid arbitrary changes to field order and types; use <span>static_assert</span>/check sizeof when necessary;
• • C++ exported interfaces must use <span>extern "C"</span> to ensure C ABI and symbol names;
• • Clearly declare calling conventions; on Windows, it is recommended to use <span>__cdecl</span> or a consistent convention;
• • Dynamic library/plugin interfaces should only expose C language APIs, not C++ or complex structures;
• • Document all ABI details and follow backward compatibility principles during upgrades;
• • Compile separately for different platforms/architectures; mixing 32/64-bit objects is strictly prohibited;
• • When upgrading libraries, use version numbers/symbol versioning mechanisms to avoid crashing old programs。

4. Comparison of Typical Error Code and Optimized Correct Code

Error Example 1: Interface Structure Change Leading to Crash

// Old library
typedef struct { int a; float b; } Foo;

// New library
typedef struct { int a; double c; float b; } Foo;
// The layout of Foo in the main program and library is inconsistent, leading to crashes/data corruption

Correct Approach:

• • Changes to interface structures should be prohibited. Create new structures or use version numbers for upgrades.

Error Example 2: C++ Interface Not Using extern “C”

// plugin.cpp
void plugin_init() { /* ... */ }
// Exported symbol is _Z11plugin_initv, which cannot be found using C methods

Correct Approach:

extern "C" void plugin_init() { /* ... */ }

Error Example 3: Inconsistent Calling Conventions

// lib.c
__stdcall void foo(int a);

// main.c
void foo(int a); // Default __cdecl
// Stack corruption after the call

Correct Approach:

• • Clearly declare and consistently use calling conventions.

5. Necessary Explanation of Underlying Principles

• • Structure layout is determined by the compiler and may vary due to alignment, padding, and order changes;
• • Name Mangling allows C++ to support overloading but disrupts C ABI consistency;
• • Calling conventions determine how parameters are passed on the stack/registers and how stack frames are cleaned up;
• • CRT differences can lead to inconsistencies in global state, handles, and memory pools, making mixing very prone to crashes.

6. Illustration of Structure Layout Differences

7. Summary and Practical Recommendations

• • C language ABI compatibility is the fundamental guarantee for cross-module cooperation; any small difference can lead to serious bugs;
• • The entire development, compilation, and deployment chain must maintain ABI consistency (compiler, parameters, structures, calling conventions, etc.);
• • Only expose stable C APIs, and pay attention to backward compatibility and version identification during upgrades;
• • Design of structures/unions/callbacks and other interfaces must be extremely cautious, prohibiting arbitrary changes;
• • In engineering practice, all ABI-related changes must have detailed documentation and version management; arbitrary decisions should never be made!

Core Recommendation: Always prioritize ABI compatibility as the “lifeline” in cross-module project design, manage it meticulously, and avoid any unconscious damage to ensure the long-term stability and maintainability of C projects.