ld: VERSION
1
1 3.9 VERSION Command
1 ===================
1
1 The linker supports symbol versions when using ELF. Symbol versions are
1 only useful when using shared libraries. The dynamic linker can use
1 symbol versions to select a specific version of a function when it runs
1 a program that may have been linked against an earlier version of the
1 shared library.
1
1 You can include a version script directly in the main linker script,
1 or you can supply the version script as an implicit linker script. You
1 can also use the '--version-script' linker option.
1
1 The syntax of the 'VERSION' command is simply
1 VERSION { version-script-commands }
1
1 The format of the version script commands is identical to that used
1 by Sun's linker in Solaris 2.5. The version script defines a tree of
1 version nodes. You specify the node names and interdependencies in the
1 version script. You can specify which symbols are bound to which
1 version nodes, and you can reduce a specified set of symbols to local
1 scope so that they are not globally visible outside of the shared
1 library.
1
1 The easiest way to demonstrate the version script language is with a
1 few examples.
1
1 VERS_1.1 {
1 global:
1 foo1;
1 local:
1 old*;
1 original*;
1 new*;
1 };
1
1 VERS_1.2 {
1 foo2;
1 } VERS_1.1;
1
1 VERS_2.0 {
1 bar1; bar2;
1 extern "C++" {
1 ns::*;
1 "f(int, double)";
1 };
1 } VERS_1.2;
1
1 This example version script defines three version nodes. The first
1 version node defined is 'VERS_1.1'; it has no other dependencies. The
1 script binds the symbol 'foo1' to 'VERS_1.1'. It reduces a number of
1 symbols to local scope so that they are not visible outside of the
1 shared library; this is done using wildcard patterns, so that any symbol
1 whose name begins with 'old', 'original', or 'new' is matched. The
1 wildcard patterns available are the same as those used in the shell when
1 matching filenames (also known as "globbing"). However, if you specify
1 the symbol name inside double quotes, then the name is treated as
1 literal, rather than as a glob pattern.
1
1 Next, the version script defines node 'VERS_1.2'. This node depends
1 upon 'VERS_1.1'. The script binds the symbol 'foo2' to the version node
1 'VERS_1.2'.
1
1 Finally, the version script defines node 'VERS_2.0'. This node
1 depends upon 'VERS_1.2'. The scripts binds the symbols 'bar1' and
1 'bar2' are bound to the version node 'VERS_2.0'.
1
1 When the linker finds a symbol defined in a library which is not
1 specifically bound to a version node, it will effectively bind it to an
1 unspecified base version of the library. You can bind all otherwise
1 unspecified symbols to a given version node by using 'global: *;'
1 somewhere in the version script. Note that it's slightly crazy to use
1 wildcards in a global spec except on the last version node. Global
1 wildcards elsewhere run the risk of accidentally adding symbols to the
1 set exported for an old version. That's wrong since older versions
1 ought to have a fixed set of symbols.
1
1 The names of the version nodes have no specific meaning other than
1 what they might suggest to the person reading them. The '2.0' version
1 could just as well have appeared in between '1.1' and '1.2'. However,
1 this would be a confusing way to write a version script.
1
1 Node name can be omitted, provided it is the only version node in the
1 version script. Such version script doesn't assign any versions to
1 symbols, only selects which symbols will be globally visible out and
1 which won't.
1
1 { global: foo; bar; local: *; };
1
1 When you link an application against a shared library that has
1 versioned symbols, the application itself knows which version of each
1 symbol it requires, and it also knows which version nodes it needs from
1 each shared library it is linked against. Thus at runtime, the dynamic
1 loader can make a quick check to make sure that the libraries you have
1 linked against do in fact supply all of the version nodes that the
1 application will need to resolve all of the dynamic symbols. In this
1 way it is possible for the dynamic linker to know with certainty that
1 all external symbols that it needs will be resolvable without having to
1 search for each symbol reference.
1
1 The symbol versioning is in effect a much more sophisticated way of
1 doing minor version checking that SunOS does. The fundamental problem
1 that is being addressed here is that typically references to external
1 functions are bound on an as-needed basis, and are not all bound when
1 the application starts up. If a shared library is out of date, a
1 required interface may be missing; when the application tries to use
1 that interface, it may suddenly and unexpectedly fail. With symbol
1 versioning, the user will get a warning when they start their program if
1 the libraries being used with the application are too old.
1
1 There are several GNU extensions to Sun's versioning approach. The
1 first of these is the ability to bind a symbol to a version node in the
1 source file where the symbol is defined instead of in the versioning
1 script. This was done mainly to reduce the burden on the library
1 maintainer. You can do this by putting something like:
1 __asm__(".symver original_foo,foo@VERS_1.1");
1 in the C source file. This renames the function 'original_foo' to be an
1 alias for 'foo' bound to the version node 'VERS_1.1'. The 'local:'
1 directive can be used to prevent the symbol 'original_foo' from being
1 exported. A '.symver' directive takes precedence over a version script.
1
1 The second GNU extension is to allow multiple versions of the same
1 function to appear in a given shared library. In this way you can make
1 an incompatible change to an interface without increasing the major
1 version number of the shared library, while still allowing applications
1 linked against the old interface to continue to function.
1
1 To do this, you must use multiple '.symver' directives in the source
1 file. Here is an example:
1
1 __asm__(".symver original_foo,foo@");
1 __asm__(".symver old_foo,foo@VERS_1.1");
1 __asm__(".symver old_foo1,foo@VERS_1.2");
1 __asm__(".symver new_foo,foo@@VERS_2.0");
1
1 In this example, 'foo@' represents the symbol 'foo' bound to the
1 unspecified base version of the symbol. The source file that contains
1 this example would define 4 C functions: 'original_foo', 'old_foo',
1 'old_foo1', and 'new_foo'.
1
1 When you have multiple definitions of a given symbol, there needs to
1 be some way to specify a default version to which external references to
1 this symbol will be bound. You can do this with the 'foo@@VERS_2.0'
1 type of '.symver' directive. You can only declare one version of a
1 symbol as the default in this manner; otherwise you would effectively
1 have multiple definitions of the same symbol.
1
1 If you wish to bind a reference to a specific version of the symbol
1 within the shared library, you can use the aliases of convenience (i.e.,
1 'old_foo'), or you can use the '.symver' directive to specifically bind
1 to an external version of the function in question.
1
1 You can also specify the language in the version script:
1
1 VERSION extern "lang" { version-script-commands }
1
1 The supported 'lang's are 'C', 'C++', and 'Java'. The linker will
1 iterate over the list of symbols at the link time and demangle them
1 according to 'lang' before matching them to the patterns specified in
1 'version-script-commands'. The default 'lang' is 'C'.
1
1 Demangled names may contains spaces and other special characters. As
1 described above, you can use a glob pattern to match demangled names, or
1 you can use a double-quoted string to match the string exactly. In the
1 latter case, be aware that minor differences (such as differing
1 whitespace) between the version script and the demangler output will
1 cause a mismatch. As the exact string generated by the demangler might
1 change in the future, even if the mangled name does not, you should
1 check that all of your version directives are behaving as you expect
1 when you upgrade.
1