223 lines
12 KiB
HTML
223 lines
12 KiB
HTML
<html lang="en">
|
|
<head>
|
|
<title>VERSION - Untitled</title>
|
|
<meta http-equiv="Content-Type" content="text/html">
|
|
<meta name="description" content="Untitled">
|
|
<meta name="generator" content="makeinfo 4.13">
|
|
<link title="Top" rel="start" href="index.html#Top">
|
|
<link rel="up" href="Scripts.html#Scripts" title="Scripts">
|
|
<link rel="prev" href="PHDRS.html#PHDRS" title="PHDRS">
|
|
<link rel="next" href="Expressions.html#Expressions" title="Expressions">
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
|
<!--
|
|
This file documents the GNU linker LD
|
|
(GNU Toolchain for the A-profile Architecture 9.2-2019.12 (arm-9.10))
|
|
version 2.33.1.
|
|
|
|
Copyright (C) 1991-2019 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
|
Back-Cover Texts. A copy of the license is included in the
|
|
section entitled ``GNU Free Documentation License''.-->
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
|
<style type="text/css"><!--
|
|
pre.display { font-family:inherit }
|
|
pre.format { font-family:inherit }
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
|
pre.smallexample { font-size:smaller }
|
|
pre.smalllisp { font-size:smaller }
|
|
span.sc { font-variant:small-caps }
|
|
span.roman { font-family:serif; font-weight:normal; }
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
<div class="node">
|
|
<a name="VERSION"></a>
|
|
<p>
|
|
Next: <a rel="next" accesskey="n" href="Expressions.html#Expressions">Expressions</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="PHDRS.html#PHDRS">PHDRS</a>,
|
|
Up: <a rel="up" accesskey="u" href="Scripts.html#Scripts">Scripts</a>
|
|
<hr>
|
|
</div>
|
|
|
|
<h3 class="section">3.9 VERSION Command</h3>
|
|
|
|
<p><a name="index-VERSION-_0040_007bscript-text_0040_007d-545"></a><a name="index-symbol-versions-546"></a><a name="index-version-script-547"></a><a name="index-versions-of-symbols-548"></a>The linker supports symbol versions when using ELF. Symbol versions are
|
|
only useful when using shared libraries. The dynamic linker can use
|
|
symbol versions to select a specific version of a function when it runs
|
|
a program that may have been linked against an earlier version of the
|
|
shared library.
|
|
|
|
<p>You can include a version script directly in the main linker script, or
|
|
you can supply the version script as an implicit linker script. You can
|
|
also use the ‘<samp><span class="samp">--version-script</span></samp>’ linker option.
|
|
|
|
<p>The syntax of the <code>VERSION</code> command is simply
|
|
<pre class="smallexample"> VERSION { version-script-commands }
|
|
</pre>
|
|
<p>The format of the version script commands is identical to that used by
|
|
Sun's linker in Solaris 2.5. The version script defines a tree of
|
|
version nodes. You specify the node names and interdependencies in the
|
|
version script. You can specify which symbols are bound to which
|
|
version nodes, and you can reduce a specified set of symbols to local
|
|
scope so that they are not globally visible outside of the shared
|
|
library.
|
|
|
|
<p>The easiest way to demonstrate the version script language is with a few
|
|
examples.
|
|
|
|
<pre class="smallexample"> VERS_1.1 {
|
|
global:
|
|
foo1;
|
|
local:
|
|
old*;
|
|
original*;
|
|
new*;
|
|
};
|
|
|
|
VERS_1.2 {
|
|
foo2;
|
|
} VERS_1.1;
|
|
|
|
VERS_2.0 {
|
|
bar1; bar2;
|
|
extern "C++" {
|
|
ns::*;
|
|
"f(int, double)";
|
|
};
|
|
} VERS_1.2;
|
|
</pre>
|
|
<p>This example version script defines three version nodes. The first
|
|
version node defined is ‘<samp><span class="samp">VERS_1.1</span></samp>’; it has no other dependencies.
|
|
The script binds the symbol ‘<samp><span class="samp">foo1</span></samp>’ to ‘<samp><span class="samp">VERS_1.1</span></samp>’. It reduces
|
|
a number of symbols to local scope so that they are not visible outside
|
|
of the shared library; this is done using wildcard patterns, so that any
|
|
symbol whose name begins with ‘<samp><span class="samp">old</span></samp>’, ‘<samp><span class="samp">original</span></samp>’, or ‘<samp><span class="samp">new</span></samp>’
|
|
is matched. The wildcard patterns available are the same as those used
|
|
in the shell when matching filenames (also known as “globbing”).
|
|
However, if you specify the symbol name inside double quotes, then the
|
|
name is treated as literal, rather than as a glob pattern.
|
|
|
|
<p>Next, the version script defines node ‘<samp><span class="samp">VERS_1.2</span></samp>’. This node
|
|
depends upon ‘<samp><span class="samp">VERS_1.1</span></samp>’. The script binds the symbol ‘<samp><span class="samp">foo2</span></samp>’
|
|
to the version node ‘<samp><span class="samp">VERS_1.2</span></samp>’.
|
|
|
|
<p>Finally, the version script defines node ‘<samp><span class="samp">VERS_2.0</span></samp>’. This node
|
|
depends upon ‘<samp><span class="samp">VERS_1.2</span></samp>’. The scripts binds the symbols ‘<samp><span class="samp">bar1</span></samp>’
|
|
and ‘<samp><span class="samp">bar2</span></samp>’ are bound to the version node ‘<samp><span class="samp">VERS_2.0</span></samp>’.
|
|
|
|
<p>When the linker finds a symbol defined in a library which is not
|
|
specifically bound to a version node, it will effectively bind it to an
|
|
unspecified base version of the library. You can bind all otherwise
|
|
unspecified symbols to a given version node by using ‘<samp><span class="samp">global: *;</span></samp>’
|
|
somewhere in the version script. Note that it's slightly crazy to use
|
|
wildcards in a global spec except on the last version node. Global
|
|
wildcards elsewhere run the risk of accidentally adding symbols to the
|
|
set exported for an old version. That's wrong since older versions
|
|
ought to have a fixed set of symbols.
|
|
|
|
<p>The names of the version nodes have no specific meaning other than what
|
|
they might suggest to the person reading them. The ‘<samp><span class="samp">2.0</span></samp>’ version
|
|
could just as well have appeared in between ‘<samp><span class="samp">1.1</span></samp>’ and ‘<samp><span class="samp">1.2</span></samp>’.
|
|
However, this would be a confusing way to write a version script.
|
|
|
|
<p>Node name can be omitted, provided it is the only version node
|
|
in the version script. Such version script doesn't assign any versions to
|
|
symbols, only selects which symbols will be globally visible out and which
|
|
won't.
|
|
|
|
<pre class="smallexample"> { global: foo; bar; local: *; };
|
|
</pre>
|
|
<p>When you link an application against a shared library that has versioned
|
|
symbols, the application itself knows which version of each symbol it
|
|
requires, and it also knows which version nodes it needs from each
|
|
shared library it is linked against. Thus at runtime, the dynamic
|
|
loader can make a quick check to make sure that the libraries you have
|
|
linked against do in fact supply all of the version nodes that the
|
|
application will need to resolve all of the dynamic symbols. In this
|
|
way it is possible for the dynamic linker to know with certainty that
|
|
all external symbols that it needs will be resolvable without having to
|
|
search for each symbol reference.
|
|
|
|
<p>The symbol versioning is in effect a much more sophisticated way of
|
|
doing minor version checking that SunOS does. The fundamental problem
|
|
that is being addressed here is that typically references to external
|
|
functions are bound on an as-needed basis, and are not all bound when
|
|
the application starts up. If a shared library is out of date, a
|
|
required interface may be missing; when the application tries to use
|
|
that interface, it may suddenly and unexpectedly fail. With symbol
|
|
versioning, the user will get a warning when they start their program if
|
|
the libraries being used with the application are too old.
|
|
|
|
<p>There are several GNU extensions to Sun's versioning approach. The
|
|
first of these is the ability to bind a symbol to a version node in the
|
|
source file where the symbol is defined instead of in the versioning
|
|
script. This was done mainly to reduce the burden on the library
|
|
maintainer. You can do this by putting something like:
|
|
<pre class="smallexample"> __asm__(".symver original_foo,foo@VERS_1.1");
|
|
</pre>
|
|
<p class="noindent">in the C source file. This renames the function ‘<samp><span class="samp">original_foo</span></samp>’ to
|
|
be an alias for ‘<samp><span class="samp">foo</span></samp>’ bound to the version node ‘<samp><span class="samp">VERS_1.1</span></samp>’.
|
|
The ‘<samp><span class="samp">local:</span></samp>’ directive can be used to prevent the symbol
|
|
‘<samp><span class="samp">original_foo</span></samp>’ from being exported. A ‘<samp><span class="samp">.symver</span></samp>’ directive
|
|
takes precedence over a version script.
|
|
|
|
<p>The second GNU extension is to allow multiple versions of the same
|
|
function to appear in a given shared library. In this way you can make
|
|
an incompatible change to an interface without increasing the major
|
|
version number of the shared library, while still allowing applications
|
|
linked against the old interface to continue to function.
|
|
|
|
<p>To do this, you must use multiple ‘<samp><span class="samp">.symver</span></samp>’ directives in the
|
|
source file. Here is an example:
|
|
|
|
<pre class="smallexample"> __asm__(".symver original_foo,foo@");
|
|
__asm__(".symver old_foo,foo@VERS_1.1");
|
|
__asm__(".symver old_foo1,foo@VERS_1.2");
|
|
__asm__(".symver new_foo,foo@@VERS_2.0");
|
|
</pre>
|
|
<p>In this example, ‘<samp><span class="samp">foo@</span></samp>’ represents the symbol ‘<samp><span class="samp">foo</span></samp>’ bound to the
|
|
unspecified base version of the symbol. The source file that contains this
|
|
example would define 4 C functions: ‘<samp><span class="samp">original_foo</span></samp>’, ‘<samp><span class="samp">old_foo</span></samp>’,
|
|
‘<samp><span class="samp">old_foo1</span></samp>’, and ‘<samp><span class="samp">new_foo</span></samp>’.
|
|
|
|
<p>When you have multiple definitions of a given symbol, there needs to be
|
|
some way to specify a default version to which external references to
|
|
this symbol will be bound. You can do this with the
|
|
‘<samp><span class="samp">foo@@VERS_2.0</span></samp>’ type of ‘<samp><span class="samp">.symver</span></samp>’ directive. You can only
|
|
declare one version of a symbol as the default in this manner; otherwise
|
|
you would effectively have multiple definitions of the same symbol.
|
|
|
|
<p>If you wish to bind a reference to a specific version of the symbol
|
|
within the shared library, you can use the aliases of convenience
|
|
(i.e., ‘<samp><span class="samp">old_foo</span></samp>’), or you can use the ‘<samp><span class="samp">.symver</span></samp>’ directive to
|
|
specifically bind to an external version of the function in question.
|
|
|
|
<p>You can also specify the language in the version script:
|
|
|
|
<pre class="smallexample"> VERSION extern "lang" { version-script-commands }
|
|
</pre>
|
|
<p>The supported ‘<samp><span class="samp">lang</span></samp>’s are ‘<samp><span class="samp">C</span></samp>’, ‘<samp><span class="samp">C++</span></samp>’, and ‘<samp><span class="samp">Java</span></samp>’.
|
|
The linker will iterate over the list of symbols at the link time and
|
|
demangle them according to ‘<samp><span class="samp">lang</span></samp>’ before matching them to the
|
|
patterns specified in ‘<samp><span class="samp">version-script-commands</span></samp>’. The default
|
|
‘<samp><span class="samp">lang</span></samp>’ is ‘<samp><span class="samp">C</span></samp>’.
|
|
|
|
<p>Demangled names may contains spaces and other special characters. As
|
|
described above, you can use a glob pattern to match demangled names,
|
|
or you can use a double-quoted string to match the string exactly. In
|
|
the latter case, be aware that minor differences (such as differing
|
|
whitespace) between the version script and the demangler output will
|
|
cause a mismatch. As the exact string generated by the demangler
|
|
might change in the future, even if the mangled name does not, you
|
|
should check that all of your version directives are behaving as you
|
|
expect when you upgrade.
|
|
|
|
</body></html>
|
|
|