|
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
- <html>
- <!-- This file documents the GNU linker LD
- (GNU Arm Embedded Toolchain 10-2020-q4-major)
- version 2.35.1.
-
- Copyright (C) 1991-2020 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". -->
- <!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <title>VERSION (LD)</title>
-
- <meta name="description" content="VERSION (LD)">
- <meta name="keywords" content="VERSION (LD)">
- <meta name="resource-type" content="document">
- <meta name="distribution" content="global">
- <meta name="Generator" content="makeinfo">
- <link href="index.html#Top" rel="start" title="Top">
- <link href="LD-Index.html#LD-Index" rel="index" title="LD Index">
- <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
- <link href="Scripts.html#Scripts" rel="up" title="Scripts">
- <link href="Expressions.html#Expressions" rel="next" title="Expressions">
- <link href="PHDRS.html#PHDRS" rel="prev" title="PHDRS">
- <style type="text/css">
- <!--
- a.summary-letter {text-decoration: none}
- blockquote.indentedblock {margin-right: 0em}
- blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
- blockquote.smallquotation {font-size: smaller}
- div.display {margin-left: 3.2em}
- div.example {margin-left: 3.2em}
- div.lisp {margin-left: 3.2em}
- div.smalldisplay {margin-left: 3.2em}
- div.smallexample {margin-left: 3.2em}
- div.smalllisp {margin-left: 3.2em}
- kbd {font-style: oblique}
- pre.display {font-family: inherit}
- pre.format {font-family: inherit}
- pre.menu-comment {font-family: serif}
- pre.menu-preformatted {font-family: serif}
- pre.smalldisplay {font-family: inherit; font-size: smaller}
- pre.smallexample {font-size: smaller}
- pre.smallformat {font-family: inherit; font-size: smaller}
- pre.smalllisp {font-size: smaller}
- span.nolinebreak {white-space: nowrap}
- span.roman {font-family: initial; font-weight: normal}
- span.sansserif {font-family: sans-serif; font-weight: normal}
- ul.no-bullet {list-style: none}
- -->
- </style>
-
-
- </head>
-
- <body lang="en">
- <a name="VERSION"></a>
- <div class="header">
- <p>
- Next: <a href="Expressions.html#Expressions" accesskey="n" rel="next">Expressions</a>, Previous: <a href="PHDRS.html#PHDRS" accesskey="p" rel="prev">PHDRS</a>, Up: <a href="Scripts.html#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
- <hr>
- <a name="VERSION-Command"></a>
- <h3 class="section">3.9 VERSION Command</h3>
- <a name="index-VERSION-_007bscript-text_007d"></a>
- <a name="index-symbol-versions"></a>
- <a name="index-version-script"></a>
- <a name="index-versions-of-symbols"></a>
- <p>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>
- <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>--version-script</samp>’ linker option.
- </p>
- <p>The syntax of the <code>VERSION</code> command is simply
- </p><div class="smallexample">
- <pre class="smallexample">VERSION { version-script-commands }
- </pre></div>
-
- <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>
- <p>The easiest way to demonstrate the version script language is with a few
- examples.
- </p>
- <div class="smallexample">
- <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></div>
-
- <p>This example version script defines three version nodes. The first
- version node defined is ‘<samp>VERS_1.1</samp>’; it has no other dependencies.
- The script binds the symbol ‘<samp>foo1</samp>’ to ‘<samp>VERS_1.1</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>old</samp>’, ‘<samp>original</samp>’, or ‘<samp>new</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>
- <p>Next, the version script defines node ‘<samp>VERS_1.2</samp>’. This node
- depends upon ‘<samp>VERS_1.1</samp>’. The script binds the symbol ‘<samp>foo2</samp>’
- to the version node ‘<samp>VERS_1.2</samp>’.
- </p>
- <p>Finally, the version script defines node ‘<samp>VERS_2.0</samp>’. This node
- depends upon ‘<samp>VERS_1.2</samp>’. The scripts binds the symbols ‘<samp>bar1</samp>’
- and ‘<samp>bar2</samp>’ are bound to the version node ‘<samp>VERS_2.0</samp>’.
- </p>
- <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>global: *;</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>
- <p>The names of the version nodes have no specific meaning other than what
- they might suggest to the person reading them. The ‘<samp>2.0</samp>’ version
- could just as well have appeared in between ‘<samp>1.1</samp>’ and ‘<samp>1.2</samp>’.
- However, this would be a confusing way to write a version script.
- </p>
- <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.
- </p>
- <div class="smallexample">
- <pre class="smallexample">{ global: foo; bar; local: *; };
- </pre></div>
-
- <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>
- <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>
- <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:
- </p><div class="smallexample">
- <pre class="smallexample">__asm__(".symver original_foo,foo@VERS_1.1");
- </pre></div>
- <p>in the C source file. This renames the function ‘<samp>original_foo</samp>’ to
- be an alias for ‘<samp>foo</samp>’ bound to the version node ‘<samp>VERS_1.1</samp>’.
- The ‘<samp>local:</samp>’ directive can be used to prevent the symbol
- ‘<samp>original_foo</samp>’ from being exported. A ‘<samp>.symver</samp>’ directive
- takes precedence over a version script.
- </p>
- <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>
- <p>To do this, you must use multiple ‘<samp>.symver</samp>’ directives in the
- source file. Here is an example:
- </p>
- <div class="smallexample">
- <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></div>
-
- <p>In this example, ‘<samp>foo@</samp>’ represents the symbol ‘<samp>foo</samp>’ bound to the
- unspecified base version of the symbol. The source file that contains this
- example would define 4 C functions: ‘<samp>original_foo</samp>’, ‘<samp>old_foo</samp>’,
- ‘<samp>old_foo1</samp>’, and ‘<samp>new_foo</samp>’.
- </p>
- <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>foo@@VERS_2.0</samp>’ type of ‘<samp>.symver</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>
- <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>old_foo</samp>’), or you can use the ‘<samp>.symver</samp>’ directive to
- specifically bind to an external version of the function in question.
- </p>
- <p>You can also specify the language in the version script:
- </p>
- <div class="smallexample">
- <pre class="smallexample">VERSION extern "lang" { version-script-commands }
- </pre></div>
-
- <p>The supported ‘<samp>lang</samp>’s are ‘<samp>C</samp>’, ‘<samp>C++</samp>’, and ‘<samp>Java</samp>’.
- The linker will iterate over the list of symbols at the link time and
- demangle them according to ‘<samp>lang</samp>’ before matching them to the
- patterns specified in ‘<samp>version-script-commands</samp>’. The default
- ‘<samp>lang</samp>’ is ‘<samp>C</samp>’.
- </p>
- <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.
- </p>
- <hr>
- <div class="header">
- <p>
- Next: <a href="Expressions.html#Expressions" accesskey="n" rel="next">Expressions</a>, Previous: <a href="PHDRS.html#PHDRS" accesskey="p" rel="prev">PHDRS</a>, Up: <a href="Scripts.html#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p>
- </div>
-
-
-
- </body>
- </html>
|
