Symbol Versioning

Allows a single library to export multiple definitions of a symbol.

Each program linked against library uses the symbol version that was current at the time of the static link.

Allows us to make an incompatible change without increasing major version number of the library.

At the extreme, symbol versioning can completely replace traditional naming scheme using major and minor version numbers.

Used in glibc: /lib/libc.so.6 contains all glibc versions from 2.0 through to 2.3.x.

Example

We demonstrate the use of symbol versioning via an example...

First we create a library that contains a single definition of a function, and build that library with a version script:

bash$ cat sv_lib_v1.c
#include 

void xyz(void) { printf("v1 xyz\n"); }
bash$ cat sv_v1.map
VER_1 {
        global: xyz;
        local:  *;      # Hide all other symbols
};

bash$ gcc -g -c -fPIC -Wall sv_lib_v1.c
bash$ gcc -g -shared -o libsv.so sv_lib_v1.o \
            -Wl,--version-script,sv_v1.map

The symbols listed under VER_1 are associated with that tag.

We then build a program that uses "version 1" of our function:

bash$ cat sv_prog.c
#include <stdlib.h>

int main(int argc, char *argv[])
{
    void xyz(void);

    xyz();
    exit(EXIT_SUCCESS);
}
bash$ gcc -g -o p1 sv_prog.c libsv.so

Running the program produces the expected result:

bash$ LD_LIBRARY_PATH=. ./p1
v1 xyz

Suppose we want to modify the definition of our function xyz(), but still want to ensure that p1 continues to use the old definition.

We create a modified version of the shared library source file:

bash$ cat sv_lib_v2.c
#include 

__asm__(".symver xyz_old,xyz@VER_1");
__asm__(".symver xyz_new,xyz@@VER_2");

void xyz_old(void) { printf("v1 xyz\n"); }

void xyz_new(void) { printf("v2 xyz\n"); }

void pqr(void) { printf("v2 pqr()\n"); }

The two versions of xyz() are provided by xyz_old() and xyz_new().

The .symver assembler directives are the "glue" tying the different versions of xyz() to version tags in the modified version scribt (shown in a moment)

.symver xyz_old,xyz@VER_1 says that says that xyz_old() is the implementation of xyz() to be used by applications linked against version tag VER_1.

.symver xyz_new,xyz@@VER_2 says that says that xyz_new() is the implementation of xyz() to be used by applications linked against version tag VER_2.

The @@ in the second .symver directive says that this is the default definition of xyz that should be used by applications that link against this version of the library.

Exactly one definition must be marked with @@.

pqr() is a new function that is exported by this library version.

bash$ cat sv_v2.map
VER_1 {
        global: xyz;
        local:  *;      # Hide all other symbols
};

VER_2 {
        global: xyz; pqr;
        local:  *;      # Hide all other symbols
};

Version tag names have no significance in themselves; should choose them to be meaningful.