Skip to content

Examples & Case Encyclopedia

This catalog covers 190 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.json and are the single source of truth β€” these pages are generated from that file plus per-case README.md files under examples/.

Verdict distribution

Verdict Count What it means
πŸ”΄ BREAKING 107 ABI breaks: existing consumers will fail at runtime.
🟠 API_BREAK 17 Source-level / API-only breaks; recompilation fails or behavior shifts.
🟑 COMPATIBLE_WITH_RISK 29 Backward-compatible at the symbol level but with behavioral risk.
🟒 COMPATIBLE 30 Backward-compatible changes (additions or quality-only).
βœ… NO_CHANGE 7 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 107 Listed in BREAKING_KINDS β€” runtime ABI break.
API Break 17 Listed in API_BREAK_KINDS β€” source/API-level break.
Risk 29 Listed in RISK_KINDS β€” symbol-compatible but behaviorally risky.
Addition (Compatible) 9 Listed in ADDITION_KINDS β€” backward-compatible additions.
Quality (Compatible) 21 Listed in QUALITY_KINDS β€” metadata/quality issues, not ABI breaks.
No Change 7 Identical ABI/API β€” sanity-check baselines.

All cases

Gaps in the numbering are expected. Some case numbers (e.g. 84, 90–93) are multi-library bundle cases that are not part of this single-library catalog; they are documented in the repository under examples/ and indexed in examples/README.md. The list below is sorted by case number.

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
case10_return_type Return Type Change πŸ”΄ BREAKING Breaking
case11_global_var_type Global Variable Type Change πŸ”΄ BREAKING Breaking
case12_function_removed Function Removed from Shared Library πŸ”΄ BREAKING Breaking
case13_symbol_versioning Symbol Versioning Script 🟒 COMPATIBLE Quality (Compatible)
case14_cpp_class_size C++ Class Size Change πŸ”΄ BREAKING Breaking
case15_noexcept_change noexcept Removed 🟑 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 (Size Grows) πŸ”΄ 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 🟠 API_BREAK API Break
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 Method Moved Out-of-Line 🟒 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:: 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 Switched 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 Template Signature Changed πŸ”΄ 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 API Depends on Consumer Environment πŸ”΄ BREAKING Breaking
case98_cxx_standard_floor_raised C++ Standard Floor Raised 🟑 COMPATIBLE_WITH_RISK Risk
case99_experimental_graduated Experimental to Stable Graduation (Compatible) 🟒 COMPATIBLE Addition (Compatible)
case100_experimental_removed_without_replacement Experimental Declaration Removed Without Replacement πŸ”΄ BREAKING Breaking
case101_inline_namespace_version_bumped Inline Namespace Version Bumped πŸ”΄ BREAKING Breaking
case102_frozen_runtime_signature_changed Frozen Runtime Signature Changed πŸ”΄ BREAKING Breaking
case103_toolchain_flag_drift Toolchain Flag Drift 🟒 COMPATIBLE Quality (Compatible)
case104_glibcxx_dual_abi_flip libstdc++ Dual-ABI Flip πŸ”΄ BREAKING Breaking
case105_concept_tightening Concept Tightening (C++20) 🟠 API_BREAK API Break
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
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 🟠 API_BREAK API Break
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 dedicated 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
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 Field Growth πŸ”΄ BREAKING Breaking
case122_template_signature_uninstantiated Uninstantiated Template Signature Change 🟑 COMPATIBLE_WITH_RISK Risk
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 Changed πŸ”΄ BREAKING Breaking
case128_symbol_binding_strengthened Symbol Binding Strengthened (Weak β†’ Global) 🟒 COMPATIBLE Quality (Compatible)
case129_struct_return_convention Struct-Return Convention Change πŸ”΄ 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 🟑 COMPATIBLE_WITH_RISK Risk
case133_tls_model_flip TLS Model Flip 🟑 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
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 Quality (Compatible)
case144_audit_private_header_leak Private Header Leak (Single-Release Audit) 🟒 COMPATIBLE Quality (Compatible)
case145_audit_unversioned_export Unversioned Export Under a Versioning Scheme (Audit, Pure L0) 🟒 COMPATIBLE Quality (Compatible)
case146_audit_rtti_for_internal RTTI Exported for an Internal Type (Single-Release Audit) 🟒 COMPATIBLE Quality (Compatible)
case147_scan_depth_ladder Depth Ladder β€” the Same Input Answered at Increasing Depth 🟒 COMPATIBLE Quality (Compatible)
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
case150_xcheck_export_public_pair Bidirectional Export ↔ Declaration Pair 🟒 COMPATIBLE Quality (Compatible)
case151_xcheck_provider_matrix Provider-Agreement Matrix (Corroboration Grows With Evidence) 🟒 COMPATIBLE Quality (Compatible)
case152_enum_size_flag_flip _enum_size_flag_flip β€” Enum-size flag flip (-fshort-enums) 🟑 COMPATIBLE_WITH_RISK Risk
case153_struct_packing_flip _struct_packing_flip β€” Struct-packing mode flip (-fpack-struct) 🟑 COMPATIBLE_WITH_RISK Risk
case154_lto_mode_flip _lto_mode_flip β€” LTO mode flip (-flto) 🟑 COMPATIBLE_WITH_RISK Risk
case155_char_signedness_flip _char_signedness_flip β€” Plain-char signedness flip (-fsigned-char ↔ -funsigned-char) 🟑 COMPATIBLE_WITH_RISK Risk
case156_public_macro_removed _public_macro_removed β€” Public macro removed 🟠 API_BREAK API Break
case157_inline_function_removed Inline Function Removed 🟠 API_BREAK API Break
case158_public_typedef_removed Public Typedef Removed 🟠 API_BREAK API Break
case160_public_api_internal_dep_added Public API Gains an Internal Dependency 🟑 COMPATIBLE_WITH_RISK Risk
case161_target_dependency_added New Inter-Target Build/Link Dependency 🟑 COMPATIBLE_WITH_RISK Risk
case162_symbol_source_owner_changed Exported Symbol's Declaring File Moved 🟑 COMPATIBLE_WITH_RISK Risk
case163_python_kwarg_renamed Python Keyword Argument Renamed (Stub-Only API Break) 🟠 API_BREAK API Break
case164_preproc_conditional_field Preprocessor-Conditional Field (Build-Context False Positive) βœ… NO_CHANGE No Change
case165_polymorphic_nonvirtual_dtor Polymorphic Type Without a Virtual Destructor (New Anti-Pattern) 🟑 COMPATIBLE_WITH_RISK Risk
case166_ref_qualifier_added Method Ref-Qualifier Added (str() β†’ str() &) πŸ”΄ BREAKING Breaking
case167_base_became_virtual Base Class Became Virtual (: public Device β†’ : public virtual Device) πŸ”΄ BREAKING Breaking
case168_virtual_method_devirtualized Virtual Method Devirtualized (flush() leaves the vtable) πŸ”΄ BREAKING Breaking
case169_overload_added Overload Added to a Previously Unique Function 🟑 COMPATIBLE_WITH_RISK Risk
case170_env_runtime_floor_raised Runtime Floor Raised (glibc Relink Drift) 🟑 COMPATIBLE_WITH_RISK Risk
case171_static_tls_introduced Static TLS Introduced 🟑 COMPATIBLE_WITH_RISK Risk
case172_vtable_thunk_offset_changed Vtable Thunk Offset Changed (detected from a stripped binary) πŸ”΄ BREAKING Breaking
case173_vtt_slot_count_changed VTT Slot Count Changed (detected from a stripped binary) πŸ”΄ BREAKING Breaking
case174_secondary_vtable_group_changed Secondary Vtable Group Changed πŸ”΄ BREAKING Breaking
case175_kabi_crc_changed kABI CRC Changed πŸ”΄ BREAKING Breaking
case176_kabi_symbol_namespace_changed kABI Export Namespace Changed πŸ”΄ BREAKING Breaking
case177_long_double_abi_changed long double ABI Changed πŸ”΄ BREAKING Breaking
case178_unnamed_type_in_public_abi Unnamed Type Leaks Into the Public ABI 🟑 COMPATIBLE_WITH_RISK Risk
case179_cet_protection_weakened CET Protection Weakened 🟑 COMPATIBLE_WITH_RISK Risk
case180_symbol_binding_lost_unique Symbol Binding Lost GNU_UNIQUE 🟑 COMPATIBLE_WITH_RISK Risk
case181_xcheck_public_to_internal_dependency Public API Reaches an Internal Declaration 🟒 COMPATIBLE Quality (Compatible)
case182_accidental_export_removed_still_breaking Accidental Export Removed β€” Still Breaking Under Public-Header Scoping πŸ”΄ BREAKING Breaking
case183_internal_version_node_churn Internal ELF symbol-version node churn 🟑 COMPATIBLE_WITH_RISK Risk
case184_internal_enum_churn_scoped Internal Enum Churn, Scoped Out by Private-Header Origin βœ… NO_CHANGE No Change
case185_inherited_override_reuses_slot Inherited override reuses the base's vtable slot 🟒 COMPATIBLE Addition (Compatible)
case186_c_api_pointee_const_abi_neutral C API Pointee const-Qualification Is ABI-Neutral βœ… NO_CHANGE No Change
case187_public_struct_private_field_type Public Struct Field Retyped to an Internal Type πŸ”΄ BREAKING Breaking
case188_public_class_private_base_class Public Class Gains a Private Base Class πŸ”΄ BREAKING Breaking
case189_public_function_private_parameter_type Public Function Parameter Retyped to an Internal Type πŸ”΄ BREAKING Breaking
case190_public_inline_function_references_internal_constant Public Inline Function References Internal Constant 🟑 COMPATIBLE_WITH_RISK Risk
case191_header_only_graph_field_type Public Struct Gains a Field of a Private Type (Header-Only Graph) πŸ”΄ BREAKING Breaking
case192_call_graph_break_survives_suppression Call-Graph-Reachable Break Survives Suppression πŸ”΄ BREAKING Breaking
case193_ordinary_exported_fn_call_not_reachable Ordinary Exported Function's Internal Call Is Not Public-Reachable πŸ”΄ BREAKING Breaking
case194_header_graph_rename_reconciled Internal Dependency Target Renamed, Safely Reconciled 🟑 COMPATIBLE_WITH_RISK Risk
case195_header_graph_ambiguous_rename_not_reconciled Ambiguous Simultaneous Rename, Correctly Not Reconciled 🟑 COMPATIBLE_WITH_RISK Risk