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

How the GNU C Library handles backward compatibility

August 1, 2019
DJ Delorie
Related topics:
Developer ToolsC, C#, C++
Related products:
Developer Tools

Share:

    One of the GNU C Library's (glibc's) unwritten rules is that a program built against an old version of glibc will continue to work against newer versions of glibc. But how does this work? What hidden magic lets you call the same function with different results, just based on when you built your program?

    Add magical symbols

    This magic is called "compat symbols," which lets glibc and the static linker (the one used at build time) select from one of many implementations of a function. For example, if we look at the 32-bit libc-2.29.so's dynamic symbol table, we see three versions of the glob64 function (in 2017, the glob function was changed to handle dangling symlinks differently, which would cause older programs to crash, but that's a different story):

    $ readelf --dyn-syms -W /lib/libc-2.29.so | grep glob64
       411: 0012d0e0  7183 FUNC    GLOBAL DEFAULT   14 glob64@GLIBC_2.1
       412: 0012edb0  7183 FUNC    GLOBAL DEFAULT   14 glob64@GLIBC_2.2
       413: 000b69a0  7183 FUNC    GLOBAL DEFAULT   14 glob64@@GLIBC_2.27
    

    In your program, you only refer to glob64(). The dynamic linker (the one invoked to start your program) searches for a symbol that starts with glob64 followed by @@ and something else. The @@ tells the dynamic linker that this version is the default version. In this case, the dynamic linker finds glob64@@GLIBC_2.27, because that application binary interface (ABI) last changed in glibc 2.27. The linker replaces @@ with @ to make glob64@GLIBC_2.27, which is stored in your program's dynamic symbol table.

    If the dynamic linker doesn't find any @@ symbols, it looks for an unversioned symbol, as usual.

    Next, when your program runs the dynamic linker and sees the version numbers on all symbols, it links to the correspondingly versioned symbol, because the names now match. The only exception here is that the current version of each symbol still has @@ in the shared object, which is matched against @ in your program:

    $ readelf --dyn-syms -W myprog.x | grep glob64
         2: 00000000     0 FUNC    GLOBAL DEFAULT  UND glob64@GLIBC_2.27 (2)
    

    Now consider the case where we've built a program against version 2.26 of the C library. In that case, glibc's dynamic symbol table has something like this when you link against it:

       411: 0012d0e0  7183 FUNC    GLOBAL DEFAULT   14 glob64@GLIBC_2.1
       412: 0012edb0  7183 FUNC    GLOBAL DEFAULT   14 glob64@@GLIBC_2.2
    

    Your program would select the GLIBC_2.2 version as the "latest" symbol, and would add glob64@GLIBC_2.2 in its dynamic symbol table.

    If you run that build on a system with glibc 2.27, the dynamic linker sees that you've built against version 2.2 of that symbol, and links you to version 2.2 despite there being a newer version available.

    Change your ABI with compatibility

    Let us say you wanted to do something similar in your own library. Consider this example code:

    int lookup (int index)
    {
     . . .
    }
    

    After a few releases, you realize you want to pass a pointer to the thing you want to look up:

    int lookup (int index, void *data)
    {
     . . .
    }
    

    You can't have two copies of the same function in your library. You don't want to change the name of the function, so you write something like this:

    __asm__(".symver lookup_v2, lookup@@v2");
    int lookup_v2 (int index, void *data)
    {
     . . .
    }
    
    __asm__(".symver lookup_v1, lookup@");
    int lookup_v1 (int index)
    {
     . . .
    }
    

    We now have two differently named functions. The original code is now lookup_v1 and is set to version @, which means "no version tag, but not the default version." The dynamic symbol table has an entry lookup for this symbol, which is what your older binaries expect.

    The new function lookup_v2 is set to version @@v2, where the @@ means it is the default for any newly-linked programs. If you link a program against the new library, an entry lookup@v2 (note one @) is added to its dynamic symbol table.

    The last step here is to tell the static linker what versions you're using and what internal names to hide, using a version file like this one, which we will call mylib.vers:

    v1 {
      local: lookup_v1;
    };
    
    v2 {
      local: lookup_v2;
    };
    

    You specify this version file to the static linker with the --version-script option, like this:

      gcc . . . -Wl,--version-script,mylib.vers
    

    Note the v1 and v2 clauses corresponding to the versions we're using. We also use the local command to "hide" our internal names for the functions that implement older versions. This practice makes the (for example) lookup_v2 symbol local in scope to your library, and not visible outside it.

    Plan ahead

    In the case of glibc, versioning was used from the beginning. You can do this, too, if you add a wildcard version to your version script, like this:

    v1 {
      *;
    };
    

    This code sets the version for all of your symbols that don't already have a specific version to v1. Of course, you only want to do this before your first release, because versioning your symbols is itself an ABI change. Then, as you develop future versions of your library, you add more version clauses and list new symbols in those new clauses.

    Understand compatibility's limits

    Despite the long history of compatibility and its almost magical ability to keep old programs running, there is one scenario that compatibility can't solve. You can't run a new program on an old glibc. Well, that's not exactly true. You can build a new program that's intended to run on an old glibc if you have a copy of that old glibc and its headers around. The easiest way to do that is to install an older operating system that has the version of glibc you want, which is the typical advice of "build on the oldest platform you want to support," possibly using a more modern toolset (gcc et al.), such as Red Hat's Developer Toolset, which was created for this purpose. That way, the new program depends only on compatibility symbols that are available in that old glibc and any newer glibc. Older glibcs cannot, of course, know the future.

    Unless you can predict the future, in which case, please already have contacted me.

    Know your nits, picks, and caveats

    As this is a short article, a lot of details are glossed over. For example, the @@ syntax is merely a user-visible version of the executable and linkable format (ELF) structure's internals, which is beyond the scope of this piece.

    Although it's possible for your program to link against two dynamically shared objects (DSOs) that use two different versions of the same symbol (i.e., those two DSOs were built against different glibc versions), such a situation is not supported. The glibc developers do their best to make it work anyway, but if it breaks, you get to keep both pieces.

    Similarly, using dlsym to look up symbols in glibc (or any other versioned DSO) can result in using a different version of the symbol than other DSOs you use, with the same caveats.

    Learn more

    Here are additional materials that may interest you:

    • ld's VERSION command
    • glibc wiki: Symbol Versioning
    • "How To Write Shared Libraries" by Ulrich Drepper, Dec. 2011
    Last updated: July 29, 2019

    Recent Posts

    • More Essential AI tutorials for Node.js Developers

    • How to run a fraud detection AI model on RHEL CVMs

    • How we use software provenance at Red Hat

    • Alternatives to creating bootc images from scratch

    • How to update OpenStack Services 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

    Red Hat legal and privacy links

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

    Report a website issue