1<html lang="en"> 2<head> 3<title>VERSION - Untitled</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Untitled"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Scripts.html#Scripts" title="Scripts"> 9<link rel="prev" href="PHDRS.html#PHDRS" title="PHDRS"> 10<link rel="next" href="Expressions.html#Expressions" title="Expressions"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13This file documents the GNU linker LD 14(Sourcery CodeBench Lite 2013.11-24) 15version 2.23.52. 16 17Copyright (C) 1991-2013 Free Software Foundation, Inc. 18 19Permission is granted to copy, distribute and/or modify this document 20under the terms of the GNU Free Documentation License, Version 1.3 21or any later version published by the Free Software Foundation; 22with no Invariant Sections, with no Front-Cover Texts, and with no 23Back-Cover Texts. A copy of the license is included in the 24section entitled ``GNU Free Documentation License''.--> 25<meta http-equiv="Content-Style-Type" content="text/css"> 26<style type="text/css"><!-- 27 pre.display { font-family:inherit } 28 pre.format { font-family:inherit } 29 pre.smalldisplay { font-family:inherit; font-size:smaller } 30 pre.smallformat { font-family:inherit; font-size:smaller } 31 pre.smallexample { font-size:smaller } 32 pre.smalllisp { font-size:smaller } 33 span.sc { font-variant:small-caps } 34 span.roman { font-family:serif; font-weight:normal; } 35 span.sansserif { font-family:sans-serif; font-weight:normal; } 36--></style> 37<link rel="stylesheet" type="text/css" href="../cs.css"> 38</head> 39<body> 40<div class="node"> 41<a name="VERSION"></a> 42<p> 43Next: <a rel="next" accesskey="n" href="Expressions.html#Expressions">Expressions</a>, 44Previous: <a rel="previous" accesskey="p" href="PHDRS.html#PHDRS">PHDRS</a>, 45Up: <a rel="up" accesskey="u" href="Scripts.html#Scripts">Scripts</a> 46<hr> 47</div> 48 49<h3 class="section">3.9 VERSION Command</h3> 50 51<p><a name="index-VERSION-_0040_007bscript-text_0040_007d-502"></a><a name="index-symbol-versions-503"></a><a name="index-version-script-504"></a><a name="index-versions-of-symbols-505"></a>The linker supports symbol versions when using ELF. Symbol versions are 52only useful when using shared libraries. The dynamic linker can use 53symbol versions to select a specific version of a function when it runs 54a program that may have been linked against an earlier version of the 55shared library. 56 57 <p>You can include a version script directly in the main linker script, or 58you can supply the version script as an implicit linker script. You can 59also use the ‘<samp><span class="samp">--version-script</span></samp>’ linker option. 60 61 <p>The syntax of the <code>VERSION</code> command is simply 62<pre class="smallexample"> VERSION { version-script-commands } 63</pre> 64 <p>The format of the version script commands is identical to that used by 65Sun's linker in Solaris 2.5. The version script defines a tree of 66version nodes. You specify the node names and interdependencies in the 67version script. You can specify which symbols are bound to which 68version nodes, and you can reduce a specified set of symbols to local 69scope so that they are not globally visible outside of the shared 70library. 71 72 <p>The easiest way to demonstrate the version script language is with a few 73examples. 74 75<pre class="smallexample"> VERS_1.1 { 76 global: 77 foo1; 78 local: 79 old*; 80 original*; 81 new*; 82 }; 83 84 VERS_1.2 { 85 foo2; 86 } VERS_1.1; 87 88 VERS_2.0 { 89 bar1; bar2; 90 extern "C++" { 91 ns::*; 92 "f(int, double)"; 93 }; 94 } VERS_1.2; 95</pre> 96 <p>This example version script defines three version nodes. The first 97version node defined is ‘<samp><span class="samp">VERS_1.1</span></samp>’; it has no other dependencies. 98The script binds the symbol ‘<samp><span class="samp">foo1</span></samp>’ to ‘<samp><span class="samp">VERS_1.1</span></samp>’. It reduces 99a number of symbols to local scope so that they are not visible outside 100of the shared library; this is done using wildcard patterns, so that any 101symbol 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>’ 102is matched. The wildcard patterns available are the same as those used 103in the shell when matching filenames (also known as “globbing”). 104However, if you specify the symbol name inside double quotes, then the 105name is treated as literal, rather than as a glob pattern. 106 107 <p>Next, the version script defines node ‘<samp><span class="samp">VERS_1.2</span></samp>’. This node 108depends upon ‘<samp><span class="samp">VERS_1.1</span></samp>’. The script binds the symbol ‘<samp><span class="samp">foo2</span></samp>’ 109to the version node ‘<samp><span class="samp">VERS_1.2</span></samp>’. 110 111 <p>Finally, the version script defines node ‘<samp><span class="samp">VERS_2.0</span></samp>’. This node 112depends upon ‘<samp><span class="samp">VERS_1.2</span></samp>’. The scripts binds the symbols ‘<samp><span class="samp">bar1</span></samp>’ 113and ‘<samp><span class="samp">bar2</span></samp>’ are bound to the version node ‘<samp><span class="samp">VERS_2.0</span></samp>’. 114 115 <p>When the linker finds a symbol defined in a library which is not 116specifically bound to a version node, it will effectively bind it to an 117unspecified base version of the library. You can bind all otherwise 118unspecified symbols to a given version node by using ‘<samp><span class="samp">global: *;</span></samp>’ 119somewhere in the version script. Note that it's slightly crazy to use 120wildcards in a global spec except on the last version node. Global 121wildcards elsewhere run the risk of accidentally adding symbols to the 122set exported for an old version. That's wrong since older versions 123ought to have a fixed set of symbols. 124 125 <p>The names of the version nodes have no specific meaning other than what 126they might suggest to the person reading them. The ‘<samp><span class="samp">2.0</span></samp>’ version 127could just as well have appeared in between ‘<samp><span class="samp">1.1</span></samp>’ and ‘<samp><span class="samp">1.2</span></samp>’. 128However, this would be a confusing way to write a version script. 129 130 <p>Node name can be omitted, provided it is the only version node 131in the version script. Such version script doesn't assign any versions to 132symbols, only selects which symbols will be globally visible out and which 133won't. 134 135<pre class="smallexample"> { global: foo; bar; local: *; }; 136</pre> 137 <p>When you link an application against a shared library that has versioned 138symbols, the application itself knows which version of each symbol it 139requires, and it also knows which version nodes it needs from each 140shared library it is linked against. Thus at runtime, the dynamic 141loader can make a quick check to make sure that the libraries you have 142linked against do in fact supply all of the version nodes that the 143application will need to resolve all of the dynamic symbols. In this 144way it is possible for the dynamic linker to know with certainty that 145all external symbols that it needs will be resolvable without having to 146search for each symbol reference. 147 148 <p>The symbol versioning is in effect a much more sophisticated way of 149doing minor version checking that SunOS does. The fundamental problem 150that is being addressed here is that typically references to external 151functions are bound on an as-needed basis, and are not all bound when 152the application starts up. If a shared library is out of date, a 153required interface may be missing; when the application tries to use 154that interface, it may suddenly and unexpectedly fail. With symbol 155versioning, the user will get a warning when they start their program if 156the libraries being used with the application are too old. 157 158 <p>There are several GNU extensions to Sun's versioning approach. The 159first of these is the ability to bind a symbol to a version node in the 160source file where the symbol is defined instead of in the versioning 161script. This was done mainly to reduce the burden on the library 162maintainer. You can do this by putting something like: 163<pre class="smallexample"> __asm__(".symver original_foo,foo@VERS_1.1"); 164</pre> 165 <p class="noindent">in the C source file. This renames the function ‘<samp><span class="samp">original_foo</span></samp>’ to 166be an alias for ‘<samp><span class="samp">foo</span></samp>’ bound to the version node ‘<samp><span class="samp">VERS_1.1</span></samp>’. 167The ‘<samp><span class="samp">local:</span></samp>’ directive can be used to prevent the symbol 168‘<samp><span class="samp">original_foo</span></samp>’ from being exported. A ‘<samp><span class="samp">.symver</span></samp>’ directive 169takes precedence over a version script. 170 171 <p>The second GNU extension is to allow multiple versions of the same 172function to appear in a given shared library. In this way you can make 173an incompatible change to an interface without increasing the major 174version number of the shared library, while still allowing applications 175linked against the old interface to continue to function. 176 177 <p>To do this, you must use multiple ‘<samp><span class="samp">.symver</span></samp>’ directives in the 178source file. Here is an example: 179 180<pre class="smallexample"> __asm__(".symver original_foo,foo@"); 181 __asm__(".symver old_foo,foo@VERS_1.1"); 182 __asm__(".symver old_foo1,foo@VERS_1.2"); 183 __asm__(".symver new_foo,foo@@VERS_2.0"); 184</pre> 185 <p>In this example, ‘<samp><span class="samp">foo@</span></samp>’ represents the symbol ‘<samp><span class="samp">foo</span></samp>’ bound to the 186unspecified base version of the symbol. The source file that contains this 187example would define 4 C functions: ‘<samp><span class="samp">original_foo</span></samp>’, ‘<samp><span class="samp">old_foo</span></samp>’, 188‘<samp><span class="samp">old_foo1</span></samp>’, and ‘<samp><span class="samp">new_foo</span></samp>’. 189 190 <p>When you have multiple definitions of a given symbol, there needs to be 191some way to specify a default version to which external references to 192this symbol will be bound. You can do this with the 193‘<samp><span class="samp">foo@@VERS_2.0</span></samp>’ type of ‘<samp><span class="samp">.symver</span></samp>’ directive. You can only 194declare one version of a symbol as the default in this manner; otherwise 195you would effectively have multiple definitions of the same symbol. 196 197 <p>If you wish to bind a reference to a specific version of the symbol 198within the shared library, you can use the aliases of convenience 199(i.e., ‘<samp><span class="samp">old_foo</span></samp>’), or you can use the ‘<samp><span class="samp">.symver</span></samp>’ directive to 200specifically bind to an external version of the function in question. 201 202 <p>You can also specify the language in the version script: 203 204<pre class="smallexample"> VERSION extern "lang" { version-script-commands } 205</pre> 206 <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>’. 207The linker will iterate over the list of symbols at the link time and 208demangle them according to ‘<samp><span class="samp">lang</span></samp>’ before matching them to the 209patterns specified in ‘<samp><span class="samp">version-script-commands</span></samp>’. The default 210‘<samp><span class="samp">lang</span></samp>’ is ‘<samp><span class="samp">C</span></samp>’. 211 212 <p>Demangled names may contains spaces and other special characters. As 213described above, you can use a glob pattern to match demangled names, 214or you can use a double-quoted string to match the string exactly. In 215the latter case, be aware that minor differences (such as differing 216whitespace) between the version script and the demangler output will 217cause a mismatch. As the exact string generated by the demangler 218might change in the future, even if the mangled name does not, you 219should check that all of your version directives are behaving as you 220expect when you upgrade. 221 222 </body></html> 223 224