[The World of Linkers—Theory 13] The Library Changed. What Happens to the Old Program?

A shared-library upgrade must remain compatible with released machine code as well as source. Argument registers, structure allocation sizes, and field offsets were fixed when each client was compiled. Replacing its library does not regenerate those instructions.

Dynamic linking selects files and binds symbols at runtime; successful binding does not validate the binary interface. The ABI, Application Binary Interface, describes the machine-level contract between caller and callee. Even unchanged function names and declarations can hide a structure-layout change that makes a successfully loaded program behave incorrectly.

Shared-library loading and symbol lookup from Theory 07 provide the foundation. This chapter distinguishes changes that break old machine-code contracts, the compatibility boundaries expressed by SONAMEs and symbol versions, and the failures that analysis tools can detect. Interface design and semantic tests must address what those tools cannot prove. A structure upgrade first shows why finding a symbol is weaker than calling it correctly.

A successful load with the wrong answer

Version 1.0 of libpoint exposes a structure and two functions:

1
/* point1.h：libpoint 1.0 */
2
struct point { int x; int y; };
3
void point_init(struct point *p, int x, int y);
4
int point_sum(const struct point *p);

The client allocates an array itself:

1
/* app.c */
2
#include <stdio.h>
3
#include POINT_H
4
struct point pts[3];     /* reserve the third element */
5
int main(void) {
6
    point_init(&pts[0], 1, 2);
7
    point_init(&pts[1], 10, 20);
8
    printf("sizeof(struct point) = %zu\n", sizeof(struct point));
9
    printf("sum0 = %d, sum1 = %d\n", point_sum(&pts[0]), point_sum(&pts[1]));
10
    return 0;
11
}

Version 1.1 adds a z field, initializes it to zero, and includes it in the sum. The source uses POINT_H to select a header and HAVE_Z for the new implementation:

1
/* point.c: shared source; version 1.1 defines HAVE_Z */
2
#include POINT_H
3
void point_init(struct point *p, int x, int y) {
4
    p->x = x;
5
    p->y = y;
6
#ifdef HAVE_Z
7
    p->z = 0;            /* initialize the new field to zero */
8
#endif
9
}
10
int point_sum(const struct point *p) {
11
#ifdef HAVE_Z
12
    return p->x + p->y + p->z;
13
#else
14
    return p->x + p->y;
15
#endif
16
}

1
/* point2.h：libpoint 1.1 */
2
struct point { int x; int y; int z; };
3
void point_init(struct point *p, int x, int y);
4
int point_sum(const struct point *p);

Keep the same SONAME, compile the client against version 1, and replace only its runtime library:

1
$ mkdir -p v1 v2
2
$ gcc -g -O1 -fPIC -shared -DPOINT_H='"point1.h"' -Wl,-soname,libpoint.so.1 point.c -o v1/libpoint.so.1
3
$ ln -sf libpoint.so.1 v1/libpoint.so
4
$ gcc -O1 -DPOINT_H='"point1.h"' app.c -Lv1 -lpoint -o app
5
$ LD_LIBRARY_PATH=v1 ./app
6
sizeof(struct point) = 8
7
sum0 = 3, sum1 = 30
8
$ gcc -g -O1 -fPIC -shared -DPOINT_H='"point2.h"' -DHAVE_Z -Wl,-soname,libpoint.so.1 point.c -o v2/libpoint.so.1
9
$ LD_LIBRARY_PATH=v2 ./app
10
sizeof(struct point) = 8
11
sum0 = 13, sum1 = 30

The program starts without a warning, but sum0 becomes 13. Recompiling it against the new header restores the expected result:

1
$ ln -sf libpoint.so.1 v2/libpoint.so
2
$ gcc -O1 -DPOINT_H='"point2.h"' app.c -Lv2 -lpoint -o app_new
3
$ LD_LIBRARY_PATH=v2 ./app_new
4
sizeof(struct point) = 12
5
sum0 = 3, sum1 = 30

The old executable allocated eight bytes per point. The new library expects twelve. Its pts[0].z overlaps the old client's pts[1].x; the second initialization writes 10 there, so the first sum becomes 1 + 2 + 10. The spare third element absorbs another misplaced write in this fixture. Without it, the second initialization would also run beyond the intended array.

This mismatched layout violates the program's type and storage contract. The value 13 explains the observed machine code; it is not a portable result guaranteed for a C program with UB¹.

Why did the loader accept it?

1
$ readelf -d app | grep NEEDED
2
 0x0000000000000001 (NEEDED)             Shared library: [libpoint.so.1]
3
 0x0000000000000001 (NEEDED)             Shared library: [libc.so.6]
4
$ readelf --dyn-syms -W v2/libpoint.so.1 | grep point_
5
     5: 00000000000010f9    17 FUNC GLOBAL DEFAULT 9 point_init
6
     6: 000000000000110a    13 FUNC GLOBAL DEFAULT 9 point_sum

The required libpoint.so.1 exists, as do point_init and point_sum. Dynamic symbols describe names, addresses, sizes, binding, and coarse kinds such as FUNC or OBJECT. They do not carry the C parameter types or the structure layout needed to reject this mismatch. The old sizeof is already a constant in the client's instructions.

API and ABI describe different boundaries

An API is the source-level interface and its documented behavior. An ABI² is the contract expressed in compiled code. Source compatibility asks whether an old client can be rebuilt correctly; binary compatibility asks whether its existing executable can continue without rebuilding. Even source compatibility is more than “the compiler accepted it.”

There are at least four parts to that compiled contract:

The loader directly checks only parts of this boundary. A C function can acquire a second integer parameter without changing its symbol name; an old caller still prepares only the first. A changed enum can remain the same machine integer type while assigning that integer a different meaning.

Some common changes therefore deserve more precise treatment than “adding things is safe”:

A truly opaque, library-allocated object can grow internally. A public structure that clients allocate cannot be treated that way merely because functions take pointers to it.

Three failures the loader cannot reinterpret

Insert YELLOW between RED and GREEN:

1
/* color.h */
2
enum color { RED,
3
#ifdef V2
4
             YELLOW,
5
#endif
6
             GREEN, BLUE };
7
const char *color_name(enum color c);

1
$ gcc -O1 color_app.c v1/libcolor.so.1 -o color_app
2
$ LD_LIBRARY_PATH=v1 ./color_app
3
GREEN -> green
4
$ LD_LIBRARY_PATH=v2 ./color_app
5
GREEN -> yellow

The old client's constant for GREEN is still 1; the new library interprets 1 as YELLOW.

Next change a hash function that the header inlines into callers while the library also uses it to place values:

1
/* tab.h */
2
#define TAB_SIZE 8
3
static inline unsigned tab_hash(const char *s) {
4
    unsigned h = 0;
5
#ifdef V2
6
    while (*s) h = (h * 33) ^ (unsigned char)*s++;
7
#else
8
    while (*s) h = h * 31 + (unsigned char)*s++;
9
#endif
10
    return h % TAB_SIZE;
11
}
12
void tab_put(const char *key, int val);   /* the library selects a slot using tab_hash */
13
int tab_slot(unsigned slot);              /* read a slot */

1
$ LD_LIBRARY_PATH=v1 ./tab_app
2
apple -> slot 2 -> 7
3
$ LD_LIBRARY_PATH=v2 ./tab_app
4
apple -> slot 2 -> 0
5
$ nm -D tab_app | grep tab_
6
                 U tab_put
7
                 U tab_slot

The old caller looks in slot 2 using its old algorithm. The new library stored the value elsewhere. No dynamic tab_hash symbol exists to update: its instructions are inside the caller.

Finally insert perimeter() before a virtual area():

1
// shape.h
2
struct Shape {
3
#ifdef V2
4
    virtual int perimeter() const;
5
#endif
6
    virtual int area() const;
7
    virtual ~Shape();
8
    int side;
9
};
10
Shape *make_square(int side);

1
$ g++ -O1 shape_app.cc v1/libshape.so.1 -o shape_app
2
$ LD_LIBRARY_PATH=v1 ./shape_app
3
area = 9
4
$ LD_LIBRARY_PATH=v2 ./shape_app
5
area = 12
6
$ objdump -d --no-show-raw-insn -C shape_app | sed -n '/<main>:/,/ret/p'
7
  ...
8
  1178: mov %rax,%rbx
9
  117b: mov (%rax),%rax
10
  117e: mov %rbx,%rdi
11
  1181: call *(%rax)
12
  ...
13
  11a0: mov (%rbx),%rax
14
  11a3: mov %rbx,%rdi
15
  11a6: call *0x10(%rax)

The old call uses virtual-table slot zero. In the new object, that slot means perimeter, so a square of side three produces “area” 12. The loader does not resolve the method name again at each indirect call.

The destructor slots shift too:

1
# v1: R_X86_64_64 targets in slot order
2
0x3dd8 -> _ZNK5Shape4areaEv
3
0x3de0 -> _ZN5ShapeD1Ev
4
0x3de8 -> _ZN5ShapeD0Ev
5
# v2
6
0x3dd0 -> _ZNK5Shape9perimeterEv
7
0x3dd8 -> _ZNK5Shape4areaEv
8
0x3de0 -> _ZN5ShapeD1Ev
9
0x3de8 -> _ZN5ShapeD0Ev

Under this C++ ABI, D1 destroys the complete object and D0 also releases its storage. The old delete call selects what used to be D0, now D1. Counting global allocation/deallocation calls makes the leak visible:

1
$ g++ -O1 shape_leak.cc v1/libshape.so.1 -o shape_leak
2
$ LD_LIBRARY_PATH=v1 ./shape_leak
3
area = 9, operator new 1, operator delete 1
4
$ LD_LIBRARY_PATH=v2 ./shape_leak
5
area = 12, operator new 1, operator delete 0

Keeping names is insufficient when the broken assumptions are constants, inline instructions, or slot numbers. The options are to preserve the original contract, provide a compatible old interface, or explicitly separate an incompatible generation.

SONAMEs separate library generations

Separate build-time selection from runtime lookup. -Llib -lpoint asks the static linker to find an input under lib. After opening the shared library, it reads DT_SONAME and records that name in the new program's DT_NEEDED. At startup, the loader reads the stored dependency; it does not run the original -lpoint selection again.

DT_SONAME is a string inside ELF; a symbolic link is a filesystem relationship. Keeping them consistent is an installation arrangement. Renaming a disk file does not rewrite its SONAME. Changing the development link does not rewrite old clients' DT_NEEDED entries.

The oldest versioning boundary is the library's runtime name. An incompatible generation can use libpoint.so.2 while existing programs continue to request .1.

Three filenames serve different jobs:

1
$ gcc -O1 -fPIC -shared -DPOINT_H='"point1.h"' -Wl,-soname,libpoint.so.1 point.c -o lib/libpoint.so.1.0.0
2
$ gcc -O1 -fPIC -shared -DPOINT_H='"point2.h"' -DHAVE_Z -Wl,-soname,libpoint.so.2 point.c -o lib/libpoint.so.2.0.0
3
$ ldconfig -n -v lib
4
lib: (from <cmdline>:0)
5
	libpoint.so.1 -> libpoint.so.1.0.0 (changed)
6
	libpoint.so.2 -> libpoint.so.2.0.0 (changed)

The real file identifies an installed implementation. The SONAME link is the name runtime dependencies request. The unversioned libpoint.so is the development link used by -lpoint when building a new client.

1
$ ln -sf libpoint.so.1 lib/libpoint.so
2
$ gcc -O1 -DPOINT_H='"point1.h"' app.c -Llib -lpoint -Wl,-rpath,$W/soname/lib -o app1
3
$ ln -sf libpoint.so.2 lib/libpoint.so
4
$ gcc -O1 -DPOINT_H='"point2.h"' app.c -Llib -lpoint -Wl,-rpath,$W/soname/lib -o app2
5
$ ls -l lib
6
lrwxr-xr-x libpoint.so -> libpoint.so.2
7
lrwxr-xr-x libpoint.so.1 -> libpoint.so.1.0.0
8
-rwxr-xr-x libpoint.so.1.0.0
9
lrwxr-xr-x libpoint.so.2 -> libpoint.so.2.0.0
10
-rwxr-xr-x libpoint.so.2.0.0
11
$ readelf -d app1 | grep NEEDED | head -1
12
 0x0000000000000001 (NEEDED)             Shared library: [libpoint.so.1]
13
$ readelf -d app2 | grep NEEDED | head -1
14
 0x0000000000000001 (NEEDED)             Shared library: [libpoint.so.2]
15
$ ./app1; ./app2
16
sizeof(struct point) = 8
17
sum0 = 3, sum1 = 30
18
sizeof(struct point) = 12
19
sum0 = 3, sum1 = 30
20
$ LD_DEBUG=libs ./app1 2>&1 | grep 'trying file=.*libpoint' | tail -1
21
       664:	  trying file=$W/soname/lib/libpoint.so.1
22
$ LD_DEBUG=libs ./app2 2>&1 | grep 'trying file=.*libpoint' | tail -1
23
       666:	  trying file=$W/soname/lib/libpoint.so.2

Both programs now select the appropriate generation and produce correct results. ldconfig can manage SONAME links; changing the development link affects future links, not the DT_NEEDED strings already stored in old executables.

This separation is coarse. A process that loads two incompatible generations with colliding global symbols can still encounter interposition between them. Different filenames are not automatically independent symbol namespaces.

Libtool's arithmetic

GNU libtool's current:revision:age numbers describe an interface interval, not the application's marketing version. current is the newest interface generation, age counts how many preceding generations remain supported, and revision identifies an implementation revision without an interface change.

For the Linux convention shown here, the SONAME suffix is current - age; the real filename ends in (current-age).age.revision:

1
$ libtool --mode=compile gcc -O1 -c demo.c
2
$ libtool --mode=link gcc -o libdemo.la demo.lo -rpath /usr/local/lib -version-info 3:1:2
3
$ ls .libs | grep '^libdemo.so'
4
libdemo.so
5
libdemo.so.1
6
libdemo.so.1.2.1
7
$ readelf -d .libs/libdemo.so | grep SONAME
8
 0x000000000000000e (SONAME)             Library soname: [libdemo.so.1]

1
-version-info 0:0:0  ->  libdemo.so.0.0.0  soname libdemo.so.0
2
-version-info 1:0:1  ->  libdemo.so.0.1.0  soname libdemo.so.0
3
-version-info 1:1:1  ->  libdemo.so.0.1.1  soname libdemo.so.0
4
-version-info 2:0:0  ->  libdemo.so.2.0.0  soname libdemo.so.2
5
-version-info 3:1:2  ->  libdemo.so.1.2.1  soname libdemo.so.1

A bug fix increments revision. An interface change increments current and resets revision. A compatible addition increments age; a removal or incompatible change resets age to zero. Consequently, a SONAME number can skip values. Follow the libtool update rules, rather than copying the package release number into these fields.

Runtime packages and development packages

Runtime package names often distinguish incompatible SONAME generations; development packages provide the unversioned link. A distribution can add its own migration suffixes, so inspect package contents rather than guess them:

1
apt-get download libssl3t64 libssl-dev
2
dpkg -c libssl3t64_*.deb | grep 'libssl\.so'
3
dpkg -c libssl-dev_*.deb | grep 'libssl\.so'

The recorded Ubuntu packages were libssl3t64 and libssl-dev, version 3.5.5-1ubuntu3.7. Their roles remain useful even as package versions change: one supplies libssl.so.3, the other the link-time name and matching dependency. Other observed owners were libstdc++6, libc6, and libabigail8 for their corresponding SONAMEs.

glibc's long-lived libc.so.6 does not imply an eternally unchanged implementation. Finer-grained compatibility lives in symbol versions.

One name, two promised behaviors

SONAME selects a library; version requirements constrain symbols within it. parse_num@VERS_1 and parse_num@@VERS_2 share a base name but represent different contracts. @@ selects the default for newly linked ordinary references; a compatibility definition with one @ remains available to explicit versioned references. These are publisher-defined labels. The loader does not infer structure layout or function signatures from their numbers.

Symbol ordinals and version numbers are different indices. Only the low 15 bits of each two-byte .gnu.version entry are its number; the high bit is a separate version flag. Version definitions are linked records, not an array addressed by number times a fixed stride. Matching between files uses version names and related metadata, not coincidentally equal local numbers. The old client later numbers VERS_1 as 4, while the library numbers it as 2; both describe the same version name. glibc's version check compares a name hash and then the name string.

The diagram uses the actual libparse ordinals shown below. Its parse_num@VERS_1 is .dynsym[10], so its version entry starts 10 × 2 = 20 bytes into .gnu.version. On little-endian x86-64, bytes 02 80 encode 0x8002; masking off 0x8000 leaves definition number 2, VERS_1. Definition .dynsym[9] has bytes 03 00, identifying number 3, the default VERS_2. This high bit belongs to the version entry, not the ELF symbol’s STV_HIDDEN visibility field.

The client follows a different relation. The old executable’s .dynsym[5] references parse_num; its version entry supplies local number 4, which .gnu.version_r describes as a VERS_1 requirement from libparse.so.1. The library uses number 2 for that same name. The loader does not compare 4 == 2: it decodes each file’s records and checks that the requested named version is supplied. The following trace concerns an explicitly versioned reference; unversioned references and dlsym follow additional compatibility rules discussed later.

ELF symbol versioning records per-symbol versions, the versions a library defines, and the versions a client requires. GNU's model allows multiple implementations of the same base name. @@ denotes the default for ordinary new references; a single @ commonly exposes a nondefault compatibility definition that can still be requested explicitly.

Start with a parser whose invalid input returns zero:

1
/* parse1.c: stop at the first nondigit; return zero if there were no digits */
2
int parse_num(const char *s) {
3
    int v = 0;
4
    while (*s >= '0' && *s <= '9') v = v * 10 + (*s++ - '0');
5
    return v;
6
}

Give the first release a version node immediately:

1
/* parse1.map */
2
VERS_1 {
3
  global: parse_num;
4
  local: *;
5
};

Version 2 should distinguish invalid input by returning minus one and add a base-selecting function. Preserve the old semantics in a compatibility implementation:

1
/* parse2.c (excerpt) */
2
/* Old implementation: associate its internal name with parse_num@VERS_1 */
3
int parse_num_v1(const char *s) { int v; digits(s, 10, &v); return v; }
4
__asm__(".symver parse_num_v1, parse_num@VERS_1");
5

6
/* New implementation: use the symver attribute to select the default version */
7
__attribute__((symver("parse_num@@VERS_2")))
8
int parse_num_v2(const char *s) { int v; return digits(s, 10, &v) ? v : -1; }
9

10
/* The new function belongs only to VERS_2 */
11
int parse_num_base(const char *s, int base) { int v; return digits(s, base, &v) ? v : -1; }

The excerpt assumes the shared internal digits helper from the supplied source. GCC's symver attribute expresses a compiler-visible association, unlike relying entirely on opaque assembly text during LTO. The version script declares the old and new nodes:

1
/* parse2.map */
2
VERS_1 {
3
  global: parse_num;
4
  local: *;
5
};
6
VERS_2 {
7
  global: parse_num; parse_num_base;
8
} VERS_1;

1
$ gcc -O1 -fPIC -shared -Wl,-soname,libparse.so.1 -Wl,--version-script=parse2.map parse2.c -o v2/libparse.so.1
2
$ readelf --dyn-syms -W v2/libparse.so.1 | grep parse_
3
    7: 000000000000124e 75 FUNC GLOBAL DEFAULT 14 parse_num_base@@VERS_2
4
    10: 00000000000011b9 69 FUNC GLOBAL DEFAULT 14 parse_num@VERS_1
5
    9: 00000000000011fe 80 FUNC GLOBAL DEFAULT 14 parse_num@@VERS_2
6
$ readelf -V v2/libparse.so.1 | sed -n '/version_d/,$p'
7
Version definition section '.gnu.version_d' contains 3 entries:
8
 Addr: 0x00000000000004e8  Offset: 0x000004e8  Link: 4 (.dynstr)
9
  000000: Rev: 1  Flags: BASE  Index: 1  Cnt: 1  Name: libparse.so.1
10
  0x001c: Rev: 1  Flags: none  Index: 2  Cnt: 1  Name: VERS_1
11
  0x0038: Rev: 1  Flags: none  Index: 3  Cnt: 2  Name: VERS_2
12
  0x0054: Parent 1: VERS_1

VERS_2 lists VERS_1 as its parent. That records the lineage but does not manufacture a missing old implementation. GNU's per-symbol version matching is more specific than simply accepting any symbol under a descendant node.

Link the same client source against each release:

1
$ gcc -O1 app.c -Lv1 -lparse -o app_old
2
$ gcc -O1 app.c -Lv2 -lparse -o app_new
3
$ readelf --dyn-syms -W app_old | grep parse_num
4
     5: 0000000000000000 0 FUNC GLOBAL DEFAULT UND parse_num@VERS_1 (4)
5
$ readelf --dyn-syms -W app_new | grep parse_num
6
     3: 0000000000000000 0 FUNC GLOBAL DEFAULT UND parse_num@VERS_2 (3)
7
$ readelf -V app_new | sed -n '/version_r/,$p'
8
Version needs section '.gnu.version_r' contains 2 entries:
9
 Addr: 0x0000000000000548 Offset: 0x00000548 Link: 5 (.dynstr)
10
  000000: Version: 1 File: libparse.so.1 Cnt: 1
11
  0x0010: Name: VERS_2 Flags: none Version: 3
12
  0x0020: Version: 1 File: libc.so.6 Cnt: 3
13
  0x0030: Name: GLIBC_2.2.5 Flags: none Version: 5
14
  0x0040: Name: GLIBC_2.3.4 Flags: none Version: 4
15
  0x0050: Name: GLIBC_2.34 Flags: none Version: 2

An ordinary reference chooses the default version available at link time and records that requirement. A new client can explicitly request the old version too:

1
#include <stdio.h>
2
extern int parse_old(const char *s);
3
__asm__(".symver parse_old,parse_num@VERS_1");
4
int main(void) {
5
    printf("explicit old: %d\n", parse_old("abc"));
6
    return 0;
7
}

1
$ gcc explicit-old.c -Lv2 -lparse -o explicit-old
2
$ LD_LIBRARY_PATH=v2 ./explicit-old
3
explicit old: 0

parse_old is a source-level alias for a versioned undefined reference; the library need not export that spelling.

Both old and new clients then run against the version-2 library:

1
$ LD_LIBRARY_PATH=v2 ./app_old
2
parse_num("42") = 42, parse_num("abc") = 0
3
$ LD_LIBRARY_PATH=v2 ./app_new
4
parse_num("42") = 42, parse_num("abc") = -1
5
$ LD_DEBUG=bindings LD_LIBRARY_PATH=v2 ./app_old 2>&1 | grep "symbol \`parse_num"
6
        45:	binding file ./app_old [0] to v2/libparse.so.1 [0]: normal symbol `parse_num' [VERS_1]
7
$ LD_DEBUG=bindings LD_LIBRARY_PATH=v2 ./app_new 2>&1 | grep "symbol \`parse_num"
8
        47:	binding file ./app_new [0] to v2/libparse.so.1 [0]: normal symbol `parse_num' [VERS_2]

The old one keeps zero for invalid input; the new one gets minus one. Reverse the compatibility direction and the requirement check fails before main:

1
$ LD_LIBRARY_PATH=v1 ./app_new
2
./app_new: v1/libparse.so.1: version `VERS_2' not found (required by ./app_new)

The loader can compare a small set of required version nodes at startup without eagerly resolving every function relocation. This catches an insufficient library version earlier than the first lazy call.

glibc's versions are identities, not necessarily distinct addresses

Inspect the installed x86-64 library:

1
readelf --dyn-syms -W /lib/x86_64-linux-gnu/libc.so.6 | grep -E ' (memcpy|memmove|fmemopen|pthread_create|__libc_start_main)@'

1
0x0b9600 IFUNC memmove@@GLIBC_2.2.5
2
0x0c22f0 FUNC  memcpy@GLIBC_2.2.5
3
0x0b8c80 IFUNC memcpy@@GLIBC_2.14
4
0x097fe0 FUNC  fmemopen@@GLIBC_2.22
5
0x0983f0 FUNC  fmemopen@GLIBC_2.2.5
6
0x0a4050 FUNC  pthread_create@GLIBC_2.2.5
7
0x0a4050 FUNC  pthread_create@@GLIBC_2.34
8
0x02a690 FUNC  __libc_start_main@GLIBC_2.2.5
9
0x02a690 FUNC  __libc_start_main@@GLIBC_2.34

The old memcpy version preserves historical compatibility behavior while the default version changed at 2.14. This does not make overlapping memcpy a valid portable C operation; new code must use memmove for overlap.

pthread_create's old and new versions point to the same address in this library. Its new default accompanies glibc 2.34's integration of libpthread. __libc_start_main also has two versions at one address, reflecting a startup-interface transition. Different version identities need not imply different instruction addresses.

fmemopen does retain distinct implementations. The old one rejects length zero; the newer one accepts it:

1
#define _GNU_SOURCE
2
#include <errno.h>
3
#include <stdio.h>
4
#include <string.h>
5
#ifdef OLD
6
__asm__(".symver fmemopen, fmemopen@GLIBC_2.2.5");
7
#endif
8
int main(void) {
9
    char buf[1];
10
    FILE *f = fmemopen(buf, 0, "r");
11
    printf("fmemopen(buf, 0, \"r\") = %s (%s)\n",
12
           f ? "FILE*" : "NULL", f ? "ok" : strerror(errno));
13
    return 0;
14
}

1
$ gcc -O1 fm.c -o fm_new
2
$ gcc -O1 -DOLD fm.c -o fm_old
3
$ objdump -T fm_new fm_old | grep fmemopen
4
... (GLIBC_2.22)  fmemopen
5
... (GLIBC_2.2.5) fmemopen
6
$ ./fm_new; ./fm_old
7
fmemopen(buf, 0, "r") = FILE* (ok)
8
fmemopen(buf, 0, "r") = NULL (Invalid argument)

Here .symver is on the reference, choosing an existing library definition. Version strings are architecture-specific contracts: an AArch64 glibc port whose baseline is 2.17 cannot be tested by copying x86-64's GLIBC_2.2.5 labels indiscriminately.

Why a new build fails on an old system

The native thread example's important references are:

1
GLIBC_2.34 __libc_start_main
2
GLIBC_2.34 pthread_create
3
GLIBC_2.34 pthread_join

Pinning only pthread_create to an old version leaves the newer pthread_join and startup requirement. __libc_start_main comes from a startup object, not the application's C source.

Run the new executable with the separately unpacked glibc 2.17 loader and its libraries:

1
S="$W/sysroot-el7"
2
"$S/lib64/ld-linux-x86-64.so.2" \
3
  --library-path "$S/lib64:$S/usr/lib64" ./th

The loader reports GLIBC_2.34 not found. The one-symbol-pinned variant fails too, as does the old-fmemopen variant because startup still requires the new interface. This tests an old userspace runtime on the same Linux kernel; it is not a full-system certification for CentOS 7.

Build with the old headers, startup files, and libraries together:

1
gcc -O1 --sysroot="$S" -B"$S/usr/lib64" \
2
    -L"$S/usr/lib64" -L"$S/lib64" th.c -lpthread -o th_el7
3
"$S/lib64/ld-linux-x86-64.so.2" \
4
  --library-path "$S/lib64:$S/usr/lib64" ./th_el7

The result prints thread returned 42 under the old loader and also runs on the current system. It requests the old thread/startup versions, plus earlier dependencies such as __stack_chk_fail@GLIBC_2.4.

Headers are part of this baseline. The current stat wrapper can request stat@GLIBC_2.33; the old headers instead use __xstat. A few hand-written .symver aliases cannot replace a coherent sysroot. Likewise, a manylinux baseline concerns the architecture and dependency set of the distributed package, not merely one executable that happened to start.

What ABI checkers can—and cannot—prove

The dynamic symbol table lacks source types, but DWARF³ can describe them. ABI tools compare reachable public types, functions, and variables across releases.

abidiff

Libabigail's abidiff reads available type information and constructs an ABI representation rooted at exported interfaces. Without usable DWARF, CTF, or BTF, its view can shrink to symbol changes.

1
$ abidiff v1/libpoint.so.1 v2/libpoint.so.1; echo "abidiff exit=$?"
2
Functions changes summary: 0 Removed, 1 Changed (1 filtered out), 0 Added functions
3
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
4

5
1 function with some indirect sub-type change:
6

7
  [C] 'function void point_init(point*, int, int)' at point.c:2:1 has some indirect sub-type changes:
8
    parameter 1 of type 'point*' has sub-type changes:
9
      in pointed to type 'struct point' at point2.h:2:1:
10
        type size changed from 64 to 96 (in bits)
11
        1 data member insertion:
12
          'int z', at offset 64 (in bits) at point2.h:2:1
13

14
abidiff exit=4

It detects the point structure growing from 64 to 96 bits and the field inserted at bit offset 64. A second function using the same changed type is filtered as redundant; --redundant displays it too.

1
$ abidiff v1/libcolor.so.1 v2/libcolor.so.1; echo "abidiff exit=$?"
2
...
3
  [C] 'function const char* color_name(color)' at color.c:2:1 has some indirect sub-type changes:
4
    parameter 1 of type 'enum color' has sub-type changes:
5
      type size hasn't changed
6
      1 enumerator insertion:
7
        'color::YELLOW' value '1'
8
      2 enumerator changes:
9
        'color::GREEN' from value '1' to '2' at color.h:2:1
10
        'color::BLUE' from value '2' to '3' at color.h:2:1
11

12
abidiff exit=4

The exit status is a bitmask. Bit 1 indicates an error; bit 2 denotes usage error and accompanies bit 1. Bit 4 means ABI change; bit 8 means a change classified as incompatible. A status containing only bit 4 requires interpretation—it is not a compatibility certificate. The virtual-table change is classified more strongly:

1
$ abidiff v1/libshape.so.1 v2/libshape.so.1; echo "abidiff exit=$?"
2
Functions changes summary: 0 Removed, 1 Changed (3 filtered out), 1 Added functions
3
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
4

5
1 Added function:
6

7
  [A] 'method virtual int Shape::perimeter() const'    {_ZNK5Shape9perimeterEv}
8
    note that this adds a new entry to the vtable of struct Shape
9

10
1 function with some indirect sub-type change:
11

12
  [C] 'method virtual int Shape::area() const' at shape.cc:5:1 has some indirect sub-type changes:
13
    the vtable offset of method virtual int Shape::area() const changed from 0 to 1
14
      note that this is an ABI incompatible change to the vtable of struct Shape
15
...
16
abidiff exit=12

Twelve is 4 | 8. A CI policy can reject explicit incompatibilities and route other changes for review, using a previous library or an abidw baseline. It must also supply the type data, including separate debug files when necessary. Stripping them weakens the evidence:

1
$ strip -o v1/libpoint.stripped.so v1/libpoint.so.1; strip -o v2/libpoint.stripped.so v2/libpoint.so.1
2
$ abidiff v1/libpoint.stripped.so v2/libpoint.stripped.so; echo "abidiff exit=$?"
3
abidiff exit=0

See the abidiff manual for the status and input rules.

abi-compliance-checker

ABICC can consume headers or ABI dumps extracted from debug-bearing libraries:

1
$ abi-dumper v1/libpoint.so.1 -o v1.dump -lver 1.0
2
WARNING: incompatible build option detected: -O1 (required -Og for better analysis)
3
$ abi-dumper v2/libpoint.so.1 -o v2.dump -lver 1.1
4
WARNING: incompatible build option detected: -O1 (required -Og for better analysis)
5
$ abi-compliance-checker -l libpoint -old v1.dump -new v2.dump -report-path report.html
6
Preparing, please wait ...
7
Comparing ABIs ...
8
Comparing APIs ...
9
Creating compatibility report ...
10
Binary compatibility: 100%
11
Source compatibility: 100%
12
Total binary compatibility problems: 0, warnings: 2
13
Total source compatibility problems: 0, warnings: 1
14
Report: report.html

For this pointer-based API, the default report gives 100% binary compatibility with low-severity warnings:

1
Field z has been added to this type.
2
1) This field will not be initialized by old clients.
3
2) Size of the inclusive type has been changed.
4
NOTE: this field should be accessed only from the new library functions, otherwise it may result in crash or incorrect behavior of applications.
5
Size of this type has been changed from 8 bytes to 12 bytes.
6
The fields or parameters of such data type may be incorrectly initialized or accessed by old client applications.

That classification reflects a real ambiguity. If the library exclusively allocated opaque points, appending a field could preserve clients. Our client allocates the public structure itself and falls into the warning's explicitly described failure case. Binary type reachability does not fully specify ownership and allocation policy.

Strict mode treats the warnings as problems:

1
$ abi-compliance-checker -l libpoint -old v1.dump -new v2.dump -strict -report-path report-strict.html
2
...
3
Binary compatibility: 75%
4
Source compatibility: 75%
5
Total binary compatibility problems: 2, warnings: 0
6
Total source compatibility problems: 1, warnings: 0
7
Report: report-strict.html
8
$ echo $?
9
1

Rebuilding with the suggested -Og retained the same default/strict distinction. Decide what report levels mean before installing an automated release gate. A successful process exit can mean “no issue above the chosen threshold,” not “every old client is safe.”

Export less before promising more

Every public symbol is a potential compatibility obligation. Internal functions should not become public merely because the compiler emits global names.

Here the library promises only fmt_width; fmt_pad changes internally:

1
/* fmt.c */
2
#ifdef V2
3
int fmt_pad(int n, char c) { return c == ' ' ? n : 0; }
4
#define PAD(n) fmt_pad(n, ' ')
5
#else
6
int fmt_pad(int n) { return n; }
7
#define PAD(n) fmt_pad(n)
8
#endif
9
#ifdef EXPORT_MACRO
10
#define FMT_API __attribute__((visibility("default")))
11
#else
12
#define FMT_API
13
#endif
14
FMT_API int fmt_width(int len, int width) { return len < width ? PAD(width - len) : 0; }

With unrestricted visibility, both are exported, and the checker correctly sees a changed public parameter list:

1
$ gcc -g -O1 -fPIC -shared fmt.c -o v1/libfmt.so
2
$ gcc -g -O1 -fPIC -shared -DV2 fmt.c -o v2/libfmt.so
3
$ abidiff v1/libfmt.so v2/libfmt.so; echo "abidiff exit=$?"
4
Functions changes summary: 0 Removed, 1 Changed, 0 Added function
5
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
6

7
1 function with some indirect sub-type change:
8

9
  [C] 'function int fmt_pad(int)' at fmt.c:6:1 has some sub-type changes:
10
    parameter 2 of type 'char' was added
11

12
abidiff exit=4

Default-hidden compilation plus an explicit export macro narrows that boundary:

1
$ gcc -g -O1 -fPIC -shared -fvisibility=hidden -DEXPORT_MACRO fmt.c -o v1/libfmt_h.so
2
$ gcc -g -O1 -fPIC -shared -fvisibility=hidden -DEXPORT_MACRO -DV2 fmt.c -o v2/libfmt_h.so
3
$ readelf --dyn-syms -W v2/libfmt.so | grep fmt_
4
     5: 0000000000001119    17 FUNC    GLOBAL DEFAULT   11 fmt_pad
5
     6: 000000000000112a    39 FUNC    GLOBAL DEFAULT   11 fmt_width
6
$ readelf --dyn-syms -W v2/libfmt_h.so | grep fmt_
7
     5: 000000000000110a    19 FUNC    GLOBAL DEFAULT    9 fmt_width
8
$ abidiff v1/libfmt_h.so v2/libfmt_h.so; echo "abidiff exit=$?"
9
abidiff exit=0

A version script can enforce the export list too:

1
$ cat fmt.map
2
FMT_1 {
3
  global: fmt_width;
4
  local: *;
5
};
6
$ gcc -g -O1 -fPIC -shared -Wl,--version-script=fmt.map fmt.c -o v1/libfmt_m.so
7
$ gcc -g -O1 -fPIC -shared -Wl,--version-script=fmt.map -DV2 fmt.c -o v2/libfmt_m.so
8
$ readelf --dyn-syms -W v2/libfmt_m.so | grep fmt_
9
     6: 000000000000110a    39 FUNC    GLOBAL DEFAULT   11 fmt_width@@FMT_1
10
$ abidiff v1/libfmt_m.so v2/libfmt_m.so; echo "abidiff exit=$?"
11
abidiff exit=0

Visibility tells the compiler earlier which definitions cannot be replaced externally; the script controls the final exported set and version names. -Bsymbolic and -fno-semantic-interposition affect binding or optimization assumptions but are not substitutes for an export allowlist.

C++ makes the remaining boundary richer. Inline functions, templates, class layouts, defaults, and virtual slots can all live in callers. Different definitions of the same entity can violate the ODR⁴ whether their out-of-line copies are unified or their inlined copies execute independently.

libstdc++'s dual ABI illustrates a deliberately designed escape: newer std::string and std::list implementations use std::__cxx11 in their binary names, allowing old and new names to coexist in libstdc++.so.6. _GLIBCXX_USE_CXX11_ABI controls the choice. Rust's native ABI offers no comparable cross-compiler stability promise by default; stable boundaries require suitable extern "C" calls, repr(C) types, and explicit ownership/error conventions. Theory 14 examines those compiler/linker contracts.

Exercises

After the main fixtures, compare the version records using the fields described above.

1. Inspect the installed ABI baseline. Scan non-symlink ELF files in /usr/bin and /usr/lib/x86_64-linux-gnu. Count each file by its highest required GLIBC_* version, preserving full dotted versions such as 2.2.5. Why does simply grepping all version strings miscount providers as consumers? Which references explain the common maxima? Then inspect libstdc++'s GLIBCXX_* and CXXABI_* nodes, the parent of GLIBCXX_3.4.30, and old/new time_get symbol pairs on that node. Do not assume that .30 is the newest node on the installed system.

2. Predict version arithmetic and lookup. Starting at libtool 4:2:1, calculate names after a bug fix, a compatible function addition, and a function removal. Separately, link a client against an unversioned parse1 library, then run it against the two-version library. Does the reference acquire a version retroactively? Which implementation is selected, and does LD_DEBUG=bindings show a bracketed version?

3. Delete compatibility in two different ways. Version 3 keeps only the new implementation. Compare these scripts:

1
/* parse3a.map: remove VERS_1 entirely */
2
VERS_2 {
3
  global: parse_num; parse_num_base;
4
  local: *;
5
};

1
/* parse3b.map: keep the VERS_1 node but remove its implementation */
2
VERS_1 {
3
  local: *;
4
};
5
VERS_2 {
6
  global: parse_num; parse_num_base;
7
} VERS_1;

Run the old versioned client. When does each failure occur, and what changes with LD_BIND_NOW=1? Restore a working old-client path.

Answers

1. Count requirements, not definitions

These are installed-system snapshots, so package changes alter the counts:

1
== Naive count: 1317 files
2
     12 GLIBC_2.2.5
3
      1 GLIBC_2.3.2
4
      3 GLIBC_2.3.4
5
     51 GLIBC_2.4
6
      4 GLIBC_2.6
7
      2 GLIBC_2.7
8
      1 GLIBC_2.8
9
     69 GLIBC_2.14
10
      1 GLIBC_2.15
11
      5 GLIBC_2.17
12
      1 GLIBC_2.25
13
      3 GLIBC_2.27
14
      2 GLIBC_2.28
15
     12 GLIBC_2.29
16
      1 GLIBC_2.31
17
      2 GLIBC_2.32
18
     15 GLIBC_2.33
19
    370 GLIBC_2.34
20
      3 GLIBC_2.35
21
      2 GLIBC_2.36
22
    695 GLIBC_2.38
23
      6 GLIBC_2.39
24
      2 GLIBC_2.41
25
     21 GLIBC_2.42
26
     33 GLIBC_2.43
27
== Count only *UND*: 1316 files
28
     15 GLIBC_2.2.5
29
      1 GLIBC_2.3.2
30
      2 GLIBC_2.3.4
31
     52 GLIBC_2.4
32
      4 GLIBC_2.6
33
      1 GLIBC_2.7
34
      1 GLIBC_2.8
35
     69 GLIBC_2.14
36
      1 GLIBC_2.15
37
      5 GLIBC_2.17
38
      1 GLIBC_2.25
39
      3 GLIBC_2.27
40
      2 GLIBC_2.28
41
     12 GLIBC_2.29
42
      2 GLIBC_2.32
43
     15 GLIBC_2.33
44
    371 GLIBC_2.34
45
      3 GLIBC_2.35
46
      2 GLIBC_2.36
47
    695 GLIBC_2.38
48
      6 GLIBC_2.39
49
      2 GLIBC_2.41
50
     21 GLIBC_2.42
51
     30 GLIBC_2.43
52
== Files classified differently by the two methods
53
/usr/lib/x86_64-linux-gnu/ld-linux-x86-64.so.2 GLIBC_2.35 -
54
/usr/lib/x86_64-linux-gnu/libc.so.6 GLIBC_2.43 GLIBC_2.35
55
/usr/lib/x86_64-linux-gnu/libc_malloc_debug.so.0 GLIBC_2.43 GLIBC_2.34
56
/usr/lib/x86_64-linux-gnu/libdl.so.2 GLIBC_2.3.4 GLIBC_2.2.5
57
/usr/lib/x86_64-linux-gnu/libm.so.6 GLIBC_2.43 GLIBC_2.4
58
/usr/lib/x86_64-linux-gnu/libpthread.so.0 GLIBC_2.31 GLIBC_2.2.5
59
/usr/lib/x86_64-linux-gnu/librt.so.1 GLIBC_2.7 GLIBC_2.2.5

Seven files differ between the two counting methods; they belong to glibc's loader/libraries and define version nodes themselves. The loader drops out when counting only undefined requirements; libc can still require loader interfaces.

In this snapshot 2.38 is the most common maximum, often from C23 entry points such as __isoc23_strtol, __isoc23_sscanf, and __isoc23_strtoul, or newer string functions. The 371 files whose maximum is 2.34 commonly depend on startup, threading, or dynamic-loading interfaces:

1
== Files with maximum requirement GLIBC_2.34, counted by referenced 2.34 symbol
2
    322 bin __libc_start_main
3
     20 lib dlsym
4
     15 lib pthread_create
5
     13 lib pthread_join
6
     12 lib pthread_setspecific
7
     12 lib pthread_key_create
8
     12 lib dlopen
9
     10 lib dlerror
10
      9 lib dlclose
11
      8 lib dladdr

Of those, 322 executables reference __libc_start_main@GLIBC_2.34. The two files with a maximum of exactly 2.36 were systemd-run through open_tree, and libXdmcp.so.6.0.0 through arc4random_buf.

The installed libstdc++ has 36 GLIBCXX_* and 19 CXXABI_* nodes. The parent of .3.4.30 is .3.4.29; nine default exports use .30, including these four time_get instances:

1
   985: 000000000018b9f0  5326 FUNC    WEAK   DEFAULT   14 _ZNKSt8time_getIwSt19istreambuf_iteratorIwSt11char_traitsIwEEE21_M_extract_via_formatES3_S3_RSt8ios_baseRSt12_Ios_IostateP2tmPKwRSt16__time_get_state@@GLIBCXX_3.4.30
2
  3280: 000000000012f290 10095 FUNC    WEAK   DEFAULT   14 _ZNKSt7__cxx118time_getIwSt19istreambuf_iteratorIwSt11char_traitsIwEEE21_M_extract_via_formatES4_S4_RSt8ios_baseRSt12_Ios_IostateP2tmPKwRSt16__time_get_state@@GLIBCXX_3.4.30
3
  3425: 000000000015bfe0  5612 FUNC    WEAK   DEFAULT   14 _ZNKSt8time_getIcSt19istreambuf_iteratorIcSt11char_traitsIcEEE21_M_extract_via_formatES3_S3_RSt8ios_baseRSt12_Ios_IostateP2tmPKcRSt16__time_get_state@@GLIBCXX_3.4.30
4
  5769: 0000000000120bc0 11768 FUNC    WEAK   DEFAULT   14 _ZNKSt7__cxx118time_getIcSt19istreambuf_iteratorIcSt11char_traitsIcEEE21_M_extract_via_formatES4_S4_RSt8ios_baseRSt12_Ios_IostateP2tmPKcRSt16__time_get_state@@GLIBCXX_3.4.30

The wchar_t pair and char pair differ by the __cxx11 namespace encoding. Sharing a version node does not imply sharing a name or object layout.

2. Compatibility intervals and unversioned clients

Initially 4:2:1 means SONAME .3 and file .3.1.2. A fix yields 4:3:1; an addition yields 5:0:2; a removal yields 6:0:0:

1
4:2:1: libfoo.so.3.1.2 soname=libfoo.so.3
2
4:3:1: libfoo.so.3.1.3 soname=libfoo.so.3
3
5:0:2: libfoo.so.3.2.0 soname=libfoo.so.3
4
6:0:0: libfoo.so.6.0.0 soname=libfoo.so.6

The SONAME jumps from 3 to 6 because age resets. It counts an interface boundary, not consecutive package majors.

The unversioned client behaves as follows:

1
$ gcc -O1 -fPIC -shared -Wl,-soname,libparse.so.1 parse1.c -o v0/libparse.so.1
2
$ gcc -O1 app.c v0/libparse.so.1 -o app_unver
3
$ readelf --dyn-syms -W app_unver | grep parse_num
4
     6: 0000000000000000     0 FUNC    GLOBAL DEFAULT  UND parse_num
5
$ readelf -V app_unver | grep -A1 'File: libparse' || echo "(no version requirement for libparse.so.1)"
6
(no version requirement for libparse.so.1)
7
$ LD_LIBRARY_PATH=v2 ./app_unver
8
parse_num("42") = 42, parse_num("abc") = 0
9
$ LD_DEBUG=bindings LD_LIBRARY_PATH=v2 ./app_unver 2>&1 | grep "symbol \`parse_num"
10
       521:	binding file ./app_unver [0] to v2/libparse.so.1 [0]: normal symbol `parse_num'

It has no stored version requirement for this library and does not acquire one by changing the runtime file. In the tested glibc compatibility lookup, the ordinary old unversioned reference selects the earliest version, producing zero. Its binding trace lacks brackets. dlsym follows a different selection rule for the public/default interface. This is a loader compatibility rule, not permission to delete published version nodes.

3. Missing version versus missing symbol within a version

1
$ LD_LIBRARY_PATH=v3a ./app_old
2
./app_old: v3a/libparse.so.1: version `VERS_1' not found (required by ./app_old)
3
$ echo $?
4
1
5
$ LD_LIBRARY_PATH=v3b ./app_old
6
./app_old: symbol lookup error: ./app_old: undefined symbol: parse_num, version VERS_1
7
$ echo $?
8
127
9
$ readelf --dyn-syms -W v3b/libparse.so.1 | grep -E 'parse|VERS'
10
     6: 0000000000000000     0 OBJECT  GLOBAL DEFAULT  ABS VERS_1
11
     7: 0000000000001209    75 FUNC    GLOBAL DEFAULT   14 parse_num_base@@VERS_2
12
     8: 0000000000000000     0 OBJECT  GLOBAL DEFAULT  ABS VERS_2
13
     9: 00000000000011b9    80 FUNC    GLOBAL DEFAULT   14 parse_num@@VERS_2

Deleting VERS_1 fails the startup version check before main. Retaining an empty node lets that coarse check pass, but the required parse_num@VERS_1 is still missing.

Build the timing probe with explicit lazy binding. A toolchain may enable immediate binding by default, so omitting flags does not establish lazy behavior. app_start.c flushes stdout after its first line, preventing buffering from hiding whether main started.

1
gcc -O1 -Wl,-z,lazy app_start.c v1/libparse.so.1 -o app_start
2
readelf -d app_start | grep -E 'FLAGS|BIND_NOW'

This build has a PIE flag but no BIND_NOW or NOW. The following environment-variable comparison then requests immediate binding.

1
$ LD_LIBRARY_PATH=v3b ./app_start
2
main started
3
./app_start: symbol lookup error: ./app_start: undefined symbol: parse_num, version VERS_1
4
$ LD_BIND_NOW=1 LD_LIBRARY_PATH=v3b ./app_start
5
./app_start: symbol lookup error: ./app_start: undefined symbol: parse_num, version VERS_1
6
$ LD_LIBRARY_PATH=v3a ./app_start
7
./app_start: v3a/libparse.so.1: version `VERS_1' not found (required by ./app_start)

With lazy binding, the latter fails on the first call, after main started. LD_BIND_NOW=1 moves it to startup. The missing-node failure is already at startup in either mode.

Restore the compatibility implementation, its symbol-version association, and the version-2 script:

1
$ gcc -O1 -fPIC -shared -Wl,-soname,libparse.so.1 -Wl,--version-script=parse2.map parse2.c -o v3fix/libparse.so.1
2
$ LD_LIBRARY_PATH=v3fix ./app_old
3
parse_num("42") = 42, parse_num("abc") = 0

If the old implementation is intentionally retired, a new SONAME marks the incompatible generation while old programs keep access to the old library.

References

Ulrich Drepper's How To Write Shared Libraries, chapter 3, develops the lifetime compatibility argument. The GNU symbol-versioning documentation, Debian shared-library policy, and libstdc++ dual-ABI manual describe the corresponding mechanisms and conventions.