8.4. Symbol versioning

Symbol versioning records extra information about a particular symbol imported from or exported from a shared library. A shared library can be updated over time. For example, a shared library might contain a function called foo. The original version of the shared library might be linked against an application which calls foo. In the future the shared library may be updated with a new version of function foo, which could contain an update. However, an old application may be tied to the original version of function foo, so both new and old versions of foo must be available in the shared library. Unfortunately, it is not possible to build a source file with two functions with exactly the same name because the static linker generates a multiply defined symbol error message. Symbol versioning works around this problem.

The examples/example_8-4 directory of this application note contains three build scripts. The first build script links an application against the original shared library, which contains the original function foo. The second build script links an application against a second version of the shared library, which contains the original version of foo and a new default version of foo. Finally, the third build script links an application against a third version of the shared library, which contains three versions of foo: the original version, the second version, and a new default version.

Where there are multiple versions of a given symbol like foo, by default armlink selects the default version of that symbol. In symbol versioning the default symbol is denoted by the @@ characters, for example:

int foo1(void) __asm__("foo@ver1");
int foo2(void) __asm__("foo@ver2");
int foo3(void) __asm__("foo@@ver3");

In this example from shared_v3.c in example 8-4, the third version of foo is the default version. If an application is linked against an older version of the symbol, the dynamic linker can detect this and fix the dynamic relocations against the correct version.

Finally, it is possible for an application to reference a symbol which is defined in multiple shared libraries. For example, the following diagram shows three modules (shared libraries), each containing the same version of the symbol foo.

Figure 8.1. Choosing a definition of a multiply defined symbol

To view this graphic, your browser must support the SVG format. Either install a browser with native support, or install an appropriate plugin such as Adobe SVG Viewer.

The dynamic linker typically performs a breadth-first search algorithm until it finds a suitable definition to resolve the reference.

In addition to the __asm__ syntax used in example 8-4, it is also possible to write a symbol version script. For more information about the scripting language, see the linker documentation.

Copyright © 2010 ARM. All rights reserved.ARM DAI 0242A