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