Examples & Case Encyclopedia¶
This catalog covers 147 cases demonstrating real-world ABI/API change scenarios for C/C++ shared libraries. Most cases are a minimal compilable v1/v2 pair plus a consumer (app.c/app.cpp) that demonstrates the actual runtime effect; some build-mode cases ship only the v1/v2 sources plus a per-side compile_commands.json.
Use this catalog to:
- Learn what kinds of changes break ABI vs. which are safe.
- See the runtime failure mode for each break (crash, wrong output, silent corruption…).
- Look up the mitigation pattern for a specific change.
- Cross-reference detected
ChangeKinds with concrete reproductions.
Ground truth. Expected verdicts and detected change kinds live in
examples/ground_truth.jsonand are the single source of truth — these pages are generated from that file plus per-caseREADME.mdfiles underexamples/.
Verdict distribution¶
| Verdict | Count | What it means |
|---|---|---|
| 🔴 BREAKING | 92 | ABI breaks: existing consumers will fail at runtime. |
| 🟠 API_BREAK | 10 | Source-level / API-only breaks; recompilation fails or behavior shifts. |
| 🟡 COMPATIBLE_WITH_RISK | 16 | Backward-compatible at the symbol level but with behavioral risk. |
| 🟢 COMPATIBLE | 23 | Backward-compatible changes (additions or quality-only). |
| ✅ NO_CHANGE | 6 | Identical ABI/API — baseline control cases. |
How to read a case page¶
Each case page starts with a metadata table (verdict, category, platforms, detected change kinds) followed by:
- What changes / what breaks — the source diff between v1 and v2.
- Why abicheck (or abidiff/ABICC) catches it — detection mechanism.
- Real Failure Demo — exact shell commands that reproduce the runtime effect.
- How to fix — the mitigation pattern, where the README documents one.
- Real-world example — historical occurrences in widely-used libraries.
- References — links to relevant standards, manuals, and abicheck source.
Source files (v1.*, v2.*, app.*, CMakeLists.txt) are listed at the bottom of every page.
Browse by category¶
| Category | Cases | What it covers |
|---|---|---|
| Breaking | 92 | Listed in BREAKING_KINDS — runtime ABI break. |
| API Break | 10 | Listed in API_BREAK_KINDS — source/API-level break. |
| Risk | 16 | Listed in RISK_KINDS — symbol-compatible but behaviorally risky. |
| Addition (Compatible) | 10 | Listed in ADDITION_KINDS — backward-compatible additions. |
| Quality (Compatible) | 13 | Listed in QUALITY_KINDS — metadata/quality issues, not ABI breaks. |
| No Change | 6 | Identical ABI/API — sanity-check baselines. |
All cases¶
| Case | Title | Verdict | Category |
|---|---|---|---|
| case01_symbol_removal | Symbol Removal | 🔴 BREAKING | Breaking |
| case02_param_type_change | Parameter Type Change | 🔴 BREAKING | Breaking |
| case03_compat_addition | Compatible Addition (New Export) | 🟢 COMPATIBLE | Addition (Compatible) |
| case04_no_change | No Change | ✅ NO_CHANGE | No Change |
| case05_soname | Missing SONAME | 🟢 COMPATIBLE | Quality (Compatible) |
| case06_visibility | Symbol Visibility Leak | 🔴 BREAKING | Breaking |
| case07_struct_layout | Struct Layout Change | 🔴 BREAKING | Breaking |
| case08_enum_value_change | Enum Value Change | 🔴 BREAKING | Breaking |
| case09_cpp_vtable | C++ Vtable Change | 🔴 BREAKING | Breaking |
| case100_experimental_removed_without_replacement | experimental:: removed without replacement (API break) | 🔴 BREAKING | Breaking |
| case101_inline_namespace_version_bumped | inline namespace version bumped (BREAKING) | 🔴 BREAKING | Breaking |
| case102_frozen_runtime_signature_changed | Frozen Runtime Signature Changed (oneTBB detail::r1 shape) |
🔴 BREAKING | Breaking |
| case103_toolchain_flag_drift | Toolchain flag drift (toolchain_flag_drift) |
🟢 COMPATIBLE | Quality (Compatible) |
| case104_glibcxx_dual_abi_flip | libstdc++ dual-ABI flip (glibcxx_dual_abi_flip_detected) |
🔴 BREAKING | Breaking |
| case105_concept_tightening | Concept Tightening (C++20) | 🟢 COMPATIBLE | Addition (Compatible) |
| case106_ctor_became_explicit | Conversion Operator Became explicit |
🟠 API_BREAK | API Break |
| case107_task_scheduler_init_removed | task_scheduler_init Removed (historical ABI break) |
🔴 BREAKING | Breaking |
| case108_task_class_removed | task Class Removed (historical ABI break — vtable angle) |
🔴 BREAKING | Breaking |
| case109_flow_graph_policy_renames | flow::graph Policy Tag Renames | 🔴 BREAKING | Breaking |
| case10_return_type | Return Type Change | 🔴 BREAKING | Breaking |
| case110_concurrent_unordered_map_api_drift | concurrent_unordered_map API Drift | 🔴 BREAKING | Breaking |
| case111_enumerable_thread_specific_lambda_ambiguity | enumerable_thread_specific Lambda-Init Ambiguity | 🟢 COMPATIBLE | Addition (Compatible) |
| case112_lp64_ilp64 | LP64 → ILP64 integer-model switch (oneMKL MKL_INT 32→64) | 🔴 BREAKING | Breaking |
| case113_abi_tag_changed | ABI-tag set change ([abi:cxx11] lost on a single symbol) | 🔴 BREAKING | Breaking |
| case114_char8t_migration | char8_t migration (C++20 char-family → char8_t) | 🔴 BREAKING | Breaking |
| case115_bit_int_width_changed | _BitInt(N) width change (C23 64 → 128) | 🔴 BREAKING | Breaking |
| case116_atomic_qualifier_changed | _Atomic qualifier added (C11) | 🔴 BREAKING | Breaking |
| case117_no_unique_address | [[no_unique_address]] layout overlay (no new ChangeKind) | 🔴 BREAKING | Breaking |
| case118_internal_struct_field_added_scoped | Internal struct gains a field (non-public, scoped) | ✅ NO_CHANGE | No Change |
| case119_internal_struct_field_removed_scoped | Internal struct loses a field (non-public, scoped) | ✅ NO_CHANGE | No Change |
| case11_global_var_type | Global Variable Type Change | 🔴 BREAKING | Breaking |
| case120_internal_struct_reordered_scoped | Internal struct fields reordered (non-public, scoped) | ✅ NO_CHANGE | No Change |
| case121_kernel_btf_struct_field_added | Kernel BTF struct grows a field (out-of-tree module break) | 🔴 BREAKING | Breaking |
| case122_template_signature_uninstantiated | Uninstantiated Template Signature Change (documented gap) | ✅ NO_CHANGE | No Change |
| case123_default_argument_removed | Default Argument Removed | 🟠 API_BREAK | API Break |
| case124_header_constant_value_changed | Header Constant Value Changed | 🟠 API_BREAK | API Break |
| case125_class_became_final | Class Became final |
🟠 API_BREAK | API Break |
| case126_sycl_device_impl_ptr | SYCL device impl pointer — shared_ptr → raw pointer |
🔴 BREAKING | Breaking |
| case127_data_object_size_changed | Exported Data Object Size Change | 🔴 BREAKING | Breaking |
| case128_symbol_binding_strengthened | Symbol Binding Strengthened (Weak → Global) | 🟢 COMPATIBLE | Quality (Compatible) |
| case129_struct_return_convention | Struct-Return Convention Change | 🔴 BREAKING | Breaking |
| case12_function_removed | Function Removed from Shared Library | 🔴 BREAKING | Breaking |
| case130_exceptions_mode_flip | Exceptions Mode Flip (-fno-exceptions) |
🟡 COMPATIBLE_WITH_RISK | Risk |
| case131_rtti_mode_flip | RTTI Mode Flip (-fno-rtti) |
🟡 COMPATIBLE_WITH_RISK | Risk |
| case132_threadsafe_statics_flip | Thread-Safe Statics Mode Flip (-fno-threadsafe-statics) |
🟡 COMPATIBLE_WITH_RISK | Risk |
| case133_tls_model_flip | TLS Model Flip (-ftls-model) |
🟡 COMPATIBLE_WITH_RISK | Risk |
| case134_relro_weakened | RELRO Weakened | 🟡 COMPATIBLE_WITH_RISK | Risk |
| case135_stack_canary_removed | Stack Canary Removed | 🟡 COMPATIBLE_WITH_RISK | Risk |
| case136_executable_stack_removed | Executable Stack Removed (the fix direction) | 🟢 COMPATIBLE | Quality (Compatible) |
| case137_runpath_changed | DT_RUNPATH Changed | 🟢 COMPATIBLE | Quality (Compatible) |
| case138_needed_added | DT_NEEDED Added | 🟢 COMPATIBLE | Quality (Compatible) |
| case139_symbol_version_node_removed | Symbol Version Node Removed | 🔴 BREAKING | Breaking |
| case13_symbol_versioning | Symbol Versioning Script | 🟢 COMPATIBLE | Quality (Compatible) |
| case140_empty_base_optimization_lost | Empty Base Optimization Lost (base subobject moved) | 🔴 BREAKING | Breaking |
| case141_versioned_symbol_scheme | Versioned-Symbol Scheme (library-wide rename) | 🔴 BREAKING | Breaking |
| case142_vtable_slot_count_binary_only | Vtable Slot Count Changed (detected from a stripped binary) | 🔴 BREAKING | Breaking |
| case143_audit_accidental_export | Accidental export (single-release audit) | 🟡 COMPATIBLE_WITH_RISK | Risk |
| case144_audit_private_header_leak | Private header leak (single-release audit) | 🟡 COMPATIBLE_WITH_RISK | Risk |
| case145_audit_unversioned_export | Unversioned export under a versioning scheme (audit, pure L0) | 🟡 COMPATIBLE_WITH_RISK | Risk |
| case146_audit_rtti_for_internal | RTTI exported for an internal type (single-release audit) | 🟡 COMPATIBLE_WITH_RISK | Risk |
| case147_scan_depth_ladder | Depth ladder: the same input answered at three depths | 🟡 COMPATIBLE_WITH_RISK | Risk |
| case148_xcheck_header_build_mismatch | Header build-context mismatch (cross-source flagship) | 🟠 API_BREAK | API Break |
| case149_xcheck_odr_variant | ODR type variant (cross-source, L4 layout ↔ layout) | 🟠 API_BREAK | API Break |
| case14_cpp_class_size | C++ Class Size Change | 🔴 BREAKING | Breaking |
| case150_xcheck_export_public_pair | Bidirectional export ↔ declaration pair | 🟡 COMPATIBLE_WITH_RISK | Risk |
| case151_xcheck_provider_matrix | Provider-agreement matrix (corroboration grows with evidence) | 🟡 COMPATIBLE_WITH_RISK | Risk |
| case15_noexcept_change | noexcept Changed |
🟡 COMPATIBLE_WITH_RISK | Risk |
| case16_inline_to_non_inline | Inline → Non-inline (ODR / Symbol Appearance) | 🟢 COMPATIBLE | Addition (Compatible) |
| case17_template_abi | Template Instantiation ABI Change | 🔴 BREAKING | Breaking |
| case18_dependency_leak | Dependency ABI Leak | 🔴 BREAKING | Breaking |
| case19_enum_member_removed | Enum Member Removed | 🔴 BREAKING | Breaking |
| case20_enum_member_value_changed | Enum Member Value Changed | 🔴 BREAKING | Breaking |
| case21_method_became_static | Method Became Static | 🔴 BREAKING | Breaking |
| case22_method_const_changed | Method Const Qualifier Changed | 🔴 BREAKING | Breaking |
| case23_pure_virtual_added | Virtual Method Became Pure Virtual | 🔴 BREAKING | Breaking |
| case24_union_field_removed | Union Field Removed | 🔴 BREAKING | Breaking |
| case25_enum_member_added | Enum Member Added | 🟢 COMPATIBLE | Addition (Compatible) |
| case26_union_field_added | Union Field Added | 🔴 BREAKING | Breaking |
| case26b_union_field_added_compatible | Union Field Added (No Size Change) | 🟢 COMPATIBLE | Addition (Compatible) |
| case27_symbol_binding_weakened | Symbol Binding Weakened (GLOBAL → WEAK) | 🟢 COMPATIBLE | Quality (Compatible) |
| case28_typedef_opaque | Typedef and Opaque Type Changes | 🔴 BREAKING | Breaking |
| case29_ifunc_transition | GNU IFUNC Transition | 🟢 COMPATIBLE | Quality (Compatible) |
| case30_field_qualifiers | Field Qualifier Changes (const, volatile) | 🔴 BREAKING | Breaking |
| case31_enum_rename | Enum Member Rename | 🟠 API_BREAK | API Break |
| case32_param_defaults | Parameter Default Value Changes (C++) | 🟠 API_BREAK | API Break |
| case33_pointer_level | - Pointer Level Change | 🔴 BREAKING | Breaking |
| case34_access_level | Access Level Changed | 🟠 API_BREAK | API Break |
| case35_field_rename | - Field Rename | 🔴 BREAKING | Breaking |
| case36_anon_struct | - Anonymous Struct/Union Change | 🔴 BREAKING | Breaking |
| case37_base_class | - Base Class Changes | 🔴 BREAKING | Breaking |
| case38_virtual_methods | Virtual Method Changes | 🔴 BREAKING | Breaking |
| case39_var_const | Variable Const Change | 🔴 BREAKING | Breaking |
| case40_field_layout | Field Layout Changes | 🔴 BREAKING | Breaking |
| case41_type_changes | Type-Level Changes | 🔴 BREAKING | Breaking |
| case42_type_alignment_changed | Type Alignment Changed (standalone alignas) | 🔴 BREAKING | Breaking |
| case43_base_class_member_added | Base Class Member Added | 🔴 BREAKING | Breaking |
| case44_cyclic_type_member_added | Cyclic Type Member Added | 🔴 BREAKING | Breaking |
| case45_multi_dim_array_change | Multi-Dimensional Array Element Type Change | 🔴 BREAKING | Breaking |
| case46_pointer_chain_type_change | Pointer Chain Type Change | 🔴 BREAKING | Breaking |
| case47_inline_to_outlined | Inline Function Moved to Outlined | 🟢 COMPATIBLE | Addition (Compatible) |
| case48_leaf_struct_through_pointer | Leaf Struct Change Propagated Through Pointer | 🔴 BREAKING | Breaking |
| case49_executable_stack | Executable Stack (GNU_STACK RWX) | 🟢 COMPATIBLE | Quality (Compatible) |
| case50_soname_inconsistent | SONAME Inconsistent (Wrong Major Version) | 🟡 COMPATIBLE_WITH_RISK | Risk |
| case51_protected_visibility | Protected Visibility (DEFAULT to PROTECTED) | 🟢 COMPATIBLE | Quality (Compatible) |
| case52_rpath_leak | RPATH Leak (Hardcoded Build Directory) | 🟢 COMPATIBLE | Quality (Compatible) |
| case53_namespace_pollution | Namespace Pollution (Generic Symbol Names) | 🔴 BREAKING | Breaking |
| case54_used_reserved_field | Used Reserved Field | 🟢 COMPATIBLE | Quality (Compatible) |
| case55_type_kind_changed | Type Kind Changed (struct → union) | 🔴 BREAKING | Breaking |
| case56_struct_packing_changed | Struct Packing Changed (pragma pack) | 🔴 BREAKING | Breaking |
| case57_enum_underlying_size_changed | Enum Underlying Size Changed | 🔴 BREAKING | Breaking |
| case58_var_removed | Global Variable Removed | 🔴 BREAKING | Breaking |
| case59_func_became_inline | Function Became Inline (outlined → inline) | 🔴 BREAKING | Breaking |
| case60_base_class_position_changed | Base Class Position Changed (Multiple Inheritance Reorder) | 🔴 BREAKING | Breaking |
| case61_var_added | Global Variable Added | 🟢 COMPATIBLE | Addition (Compatible) |
| case62_type_field_added_compatible | Type Field Added (Compatible — Opaque Struct) | 🟢 COMPATIBLE | Addition (Compatible) |
| case63_bitfield_changed | Bitfield Width Changed | 🔴 BREAKING | Breaking |
| case64_calling_convention_changed | Calling Convention Changed | 🔴 BREAKING | Breaking |
| case65_symbol_version_removed | Symbol Version Removed | 🔴 BREAKING | Breaking |
| case66_language_linkage_changed | Language Linkage Changed (extern "C" removed) | 🔴 BREAKING | Breaking |
| case67_tls_var_size_changed | TLS Variable Size Changed | 🔴 BREAKING | Breaking |
| case68_virtual_method_added | Virtual Method Added to Non-Virtual Class | 🔴 BREAKING | Breaking |
| case69_trivial_to_nontrivial | Trivially Copyable to Non-Trivial (Calling Convention Change) | 🔴 BREAKING | Breaking |
| case70_flexible_array_member_changed | Flexible Array Member Element Type Changed | 🔴 BREAKING | Breaking |
| case71_inline_namespace_moved | Inline Namespace Moved | 🔴 BREAKING | Breaking |
| case72_covariant_return_changed | Covariant Return Type Changed | 🔴 BREAKING | Breaking |
| case73_typedef_underlying_changed | Typedef Underlying Type Changed | 🔴 BREAKING | Breaking |
| case74_detail_base_class_changed | Internal detail:: base class layout change leaks via public API |
🔴 BREAKING | Breaking |
| case75_detail_embedded_by_value | Internal detail:: impl struct embedded by value |
🔴 BREAKING | Breaking |
| case76_detail_pimpl_vtable_changed | Internal detail:: polymorphic base vtable change |
🔴 BREAKING | Breaking |
| case77_detail_templated_base_changed | Internal detail:: templated base class layout change |
🔴 BREAKING | Breaking |
| case78_task_arena_attach_tag | task_arena::attach Tag Type Replaces Enum | 🔴 BREAKING | Breaking |
| case79_missing_template_instantiation | Missing template instantiation in shipped binary | 🔴 BREAKING | Breaking |
| case80_pimpl_shared_to_unique | Pimpl alias changed from shared_ptr to unique_ptr |
🔴 BREAKING | Breaking |
| case81_serialization_tag_reassigned | Serialization tag ID reassigned | 🔴 BREAKING | Breaking |
| case82_sycl_overload_set_removed | SYCL overload set removed (DPC++ build withdrawn) | 🔴 BREAKING | Breaking |
| case83_cpu_dispatch_isa_dropped | CPU-dispatch ISA family dropped | 🟡 COMPATIBLE_WITH_RISK | Risk |
| case85_internal_template_signature_changed | internal function-template signature leaks via public API (BREAKING) | 🔴 BREAKING | Breaking |
| case86_tag_struct_renamed | Tag struct renamed (empty class re-mangling) | 🔴 BREAKING | Breaking |
| case87_default_template_arg_changed | Default template argument changed | 🔴 BREAKING | Breaking |
| case88_cpo_kind_changed | CPO kind changed (BREAKING) | 🔴 BREAKING | Breaking |
| case89_inline_accessor_renamed_pimpl_member | Inline accessor references renamed pimpl member | 🔴 BREAKING | Breaking |
| case94_empty_tag_gained_state | Empty Tag Gained State | 🔴 BREAKING | Breaking |
| case95_allocator_nested_typedef_removed | Allocator Nested-Typedef Removed | 🔴 BREAKING | Breaking |
| case96_hidden_friend_removed | Hidden Friend Operator Removed | 🟠 API_BREAK | API Break |
| case97_api_depends_on_consumer_env | public API depends on consumer build environment (RISK) | 🔴 BREAKING | Breaking |
| case98_cxx_standard_floor_raised | C++ standard floor raised (per-binary: NO_CHANGE) | ✅ NO_CHANGE | No Change |
| case99_experimental_graduated | experimental → stable graduation (compatible) | 🟢 COMPATIBLE | Addition (Compatible) |