Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

abipkgdiff: Ensuring ABI compliance for shared ELF library packages

February 4, 2016
Dodji Seketeli
Related products:
Developer Tools

Share:

    Introduction

    Detecting and reviewing changes in the application binary interface (aka ABI) of ELF shared libraries has never been easier, notably since the creation of the Abigail project.  As you might already know, a tool like abidiff now allows users to analyse the cause of ABI changes and assess their impact on the forward compatibility of the shared library being considered.  It is less practical, though, to use that tool on a binary (RPM) package, because it expects individual libraries.

    Thus, this article presents abipkgdiff, a new Libabigail tool aimed at detecting incompatible ABI changes between shared libraries (or binaries in general) carried by binary packages.

    Getting abipkgdiff

    This tool is available from the Libabigail package.  On Fedora, just type (with the proper rights, obviously):

    dnf install libabigail

    On RHEL 6, RHEL 7, CentOS, you need to configure the repositories for the Extra Packages for Enterprise Linux (EPEL). Then just type (again, with the proper rights):

    yum install libabigail

    If you are not on a distribution of the Red Hat ecosystem, worry not. Binary packages of Libabigail tools are widely available on all the major GNU/Linux distributions out there.  Otherwise, you can always get the source code and compile it.

    A concrete example of ABI changes review: The Glib package in Fedora

    Let's review the ABI changes of the libraries carried by the excellent Glib package in Fedora.  We'll compare the bleeding edge version of the Glib package from Rawhide (the current Fedora development version, aka Fedora 24) against its latest stable version from Fedora 23, for the ARM architecture.

    Getting the packages to review

    To get the Fedora 24 version of the GLib package along with its debug info, please type:

    wget https://kojipkgs.fedoraproject.org//packages/glib2/2.47.5/1.fc24/armv7hl/glib2-debuginfo-2.47.5-1.fc24.armv7hl.rpm \
         https://kojipkgs.fedoraproject.org//packages/glib2/2.47.5/1.fc24/armv7hl/glib2-2.47.5-1.fc24.armv7hl.rpm

    To get the Fedora 23 version of Glib package, along with its debug info, please type:

    wget https://kojipkgs.fedoraproject.org//packages/glib2/2.46.2/1.fc23/armv7hl/glib2-debuginfo-2.46.2-1.fc23.armv7hl.rpm \
         https://kojipkgs.fedoraproject.org//packages/glib2/2.46.2/1.fc23/armv7hl/glib2-2.46.2-1.fc23.armv7hl.rpm

     

    Running abipkgdiff

    As all Libabigail tools, abipkgdiff inspects the debug info accompanying ELF binaries to get extensive information about the data types used by functions and global variables that are defined and exported.  Hence, the need for both the debug info and binary packages that we intend to review.

    Thus, the command line invocation to compare the ABIs of the glib2-2.46.2-1.fc23.armv7hl.rpm and glib2-2.47.5-1.fc24.armv7hl.rpm packages looks like:

    abipkgdiff --d1 glib2-debuginfo-2.46.2-1.fc23.armv7hl.rpm \
               --d2 glib2-debuginfo-2.47.5-1.fc24.armv7hl.rpm \
                    glib2-2.46.2-1.fc23.armv7hl.rpm glib2-2.47.5-1.fc24.armv7hl.rpm

    Note that I have artificially added '\' characters to shorten the long line and increase legibility.  Readers willing to try this command line might just do away with that '\'.

    Careful readers would have also noted how the debug info packages are provided using the --d1 and --d2 options.

    Understanding and reviewing the resulting ABI change report

    Here is what the report emitted by abipkgdiff looks like (it's been redacted for the sake of simplicity):

    ================ changes of 'libgio-2.0.so.0.4600.2'===============
      Functions changes summary: 0 Removed, 1 Changed (141 filtered out), 43 Added functions
      Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
    
      43 Added functions:
            (... a list of 43 added functions ...)
    1 function with some indirect sub-type change:
    ( ... details about sub-type changes of the function ...)
    ===== end of changes of 'libgio-2.0.so.0.4600.2'=====
    
    ======= changes of 'libglib-2.0.so.0.4600.2'========
      Functions changes summary: 0 Removed, 1 Changed (3 filtered out), 2 Added functions
      Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
    
      2 Added functions:
    ( ... a list of 2 added functions ...)
    1 function with some indirect sub-type change:
    ( ... details about sub-type changes of the function ...)
    ======== end of changes of 'libglib-2.0.so.0.4600.2'=======

     

    abipkgdiff is telling us that two shared libraries, libgio-2.0.so.0.4600.2 and libglib-2.0.so.0.4600.2, from the Glib binary package have ABI changes that are worth reviewing.

    For both libraries, two kinds of ABI changes occurred:

    • New functions were defined and exported. This kind of ABI change does not make the newer version of the library be incompatible with applications linked against its former version.  However, reviewing the list of added functions (and globally exported variables) is important to ensure that library authors really intended to export those new functions.  For people only interested in ABI changes that might introduce incompatibilities, abipkgdiff does have an option which avoid showing the list of added functions and variables.  Finding that option in the manual is left as an exercise for interested readers :-)
    • Some publicly defined and exported functions had some sub-type changes. This means there is at least one function whose return type or parameter type changed in a way that impacts the ABI.  That ABI change might cause incompatibilities that are worth looking at closely.  We'll look at this kind of ABI changes a little bit deeper.

    An interesting thing to note is how the tool filters out some changes, either because they are harmless from an ABI standpoint, or because they are redundant with the changes that are reported.  In the report summary showed above, those filtered-out changes are mentioned by the note:

    (141 filtered out)

    There is, of course, an option to show all changes without any filtering.  Another exercise for interested readers ;-)

    Functions (or variables) sub-type changes

    In all fairness, listing added or removed functions and variables is the easy game.  We don't need to look at debug info for that, do we?

    Interesting matters start when looking into changes to types which impact the ABI.  These are the so-called changes to sub-types of functions or variables.

    Here is the function sub-type change reported for the libgio-2.0.so.0.4600.2 library, in-extenso:

      1 function with some indirect sub-type change:
    
        [C]'function GDBusConnection* g_bus_get_finish(GAsyncResult*, GError**)' at gdbusconnection.c:7356:1 has some indirect sub-type changes:
          return type changed:
            in pointed to type 'typedef GDBusConnection' at giotypes.h:545:1:
              underlying type 'struct _GDBusConnection' at gdbusconnection.c:346:1 changed:
                1 data member change:
                 type of 'GDBusWorker* _GDBusConnection::worker' changed:
                   in pointed to type 'typedef GDBusWorker' at gdbusprivate.h:34:1:
                     underlying type 'struct GDBusWorker' at gdbusprivate.c:311:1 changed:
                       1 data member changes (3 filtered):
                        type of 'GSocket* GDBusWorker::socket' changed:
                          in pointed to type 'typedef GSocket' at giotypes.h:161:1:
                            underlying type 'struct _GSocket' at gsocket.h:68:1 changed:
                              1 data member change:
                               type of 'GSocketPrivate* _GSocket::priv' changed:
                                 in pointed to type 'typedef GSocketPrivate' at gsocket.h:46:1:
                                   underlying type 'struct _GSocketPrivate' at gsocket.c:231:1 changed:
                                     1 data member insertion:
                                       'guint _GSocketPrivate::connected_read', at offset 256 (in bits) at gsocket.c:245:1
                                     no data member change (1 filtered);

    The core of this change report is that a new data member named 'connected_read', of type 'guint' has been added to the type 'struct _GSocketPrivate'.  That change was made in the source code in file 'gsocket.c' at line 231. That type is somehow part of the return type of the publicly defined and exported function g_bus_get_finish.

    A cool feature of this report is that it tells us how the type that changed is related to the type of the publicly defined and exported function g_bus_get_finish which is actually an ABI entry point exported by the libgio library.

    A careful read of the report suggests that 'struct _GSocketPrivate' is actually an implementation detail for the return type of the g_bus_get_finish function: 'GDBusConnection*'.  There are several facts which lead us to that conclusion.

    One of these facts is that 'struct _GDBusConnection' is not defined in a header file (*.h), but rather in 'gdbusconnection.c'.  Note how the 'typedef GDBusConnection' (which is really struct _GDBusConnection) is declared in the header file 'giotypes.h'.  So in practice, users are not supposed to access the type 'struct _GDBusConnection', as the library authors carefully avoided to declare it in public headers.  It's an implementation detail.  So any of its sub-types are implementation details too.  As is 'struct _GSocketPrivate'.

    Fortunately, there is a way to tell abipkgdiff to ignore some ABI changes: suppression specifications.

    Suppressing change reports about implementation details

    A suppression specification tells abipkgdiff to avoid reporting changes that have certain characteristics.  In this particular case, we want to avoid showing ABI changes about types that are not defined in a header file.  The suppression specification is thus going to be a file with this content:

    [suppress_type]
      # Let's suppress change reports about types
      # not defined in header files.
      source_location_not_regexp = *\\\.h

    The meaning of this suppression specification should be obvious.  For curious readers, details of the concepts and syntax of suppression specifications can be found in the manual.  We shall call that file 'implementation-details.abignore'.  abipkgdiff can thus be invoked with the suppression specification like this:

    $ abipkgdiff --suppr implementation-details.abignore \
                 --no-added-syms \
                 --d1 glib2-debuginfo-2.46.2-1.fc23.armv7hl.rpm \
                 --d2 glib2-debuginfo-2.47.5-1.fc24.armv7hl.rpm \
                      glib2-2.46.2-1.fc23.armv7hl.rpm glib2-2.47.5-1.fc24.armv7hl.rpm
    
    $

    There are two points worth noting here:

    • the suppression specification file has been passed to the tool using the --suppr command line option
    • the --no-added-syms command line option has been added to avoid reporting added functions or variables.

    With these two additions this command now emits an empty report. This means, abipkgdiff now tells us there is no ABI change that is worth reporting, given the constraints we expressed.

    In other words, with this suppression specification, we have just come up with a an ABI incompatible change detection tool, for the Glib package.

    Glib packagers could even include that file in the package itself; abipkgdiff would then detect it and use (as the file name ends with the .abignore suffix) it as a suppression specification.

    Script writers can use the exit code of abipkgdiff to detect when the tool reports ABI changes and even know about the kind of changes it reports.  This might be useful in setting up automatic ABI incompatible change detection systems.

    Conclusion

    abipkgdiff is a useful tool to review ABI changes in binary packages.  Its sophisticated filtering capabilities are tailored to help tool writers adapt to the different coding conventions used by various upstream projects.  What might be an ABI change worth reviewing for a given project might just be a false positive for another one.  By allowing each package to provide its own way of defining what a false positive is, we hope this tool empowers package maintainers by helping them increase the signal / noise ratio while ensuring the ABI compliance of ELF shared libraries they care about.

    We welcome feedback! If you have any questions or comments relating to this article, please feel free to add it below or contact us.

    Last updated: February 24, 2024

    Recent Posts

    • AI meets containers: My first step into Podman AI Lab

    • Live migrating VMs with OpenShift Virtualization

    • Storage considerations for OpenShift Virtualization

    • Upgrade from OpenShift Service Mesh 2.6 to 3.0 with Kiali

    • EE Builder with Ansible Automation Platform on OpenShift

    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit
    © 2025 Red Hat

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue