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