path: root/development/symbolver.html

               
                                                        
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
    <head>
        <!-- Book generated using mdBook -->
        <meta charset="UTF-8">
        <title>symbol versioning - Notes</title>


        <!-- Custom HTML head -->

        <meta name="description" content="">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="theme-color" content="#ffffff">

        <link rel="icon" href="../favicon.svg">
        <link rel="shortcut icon" href="../favicon.png">
        <link rel="stylesheet" href="../css/variables.css">
        <link rel="stylesheet" href="../css/general.css">
        <link rel="stylesheet" href="../css/chrome.css">
        <link rel="stylesheet" href="../css/print.css" media="print">

        <!-- Fonts -->
        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
        <link rel="stylesheet" href="../fonts/fonts.css">

        <!-- Highlight.js Stylesheets -->
        <link rel="stylesheet" href="../highlight.css">
        <link rel="stylesheet" href="../tomorrow-night.css">
        <link rel="stylesheet" href="../ayu-highlight.css">

        <!-- Custom theme stylesheets -->


        <!-- Provide site root to javascript -->
        <script>
            var path_to_root = "../";
            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
        </script>
        <!-- Start loading toc.js asap -->
        <script src="../toc.js"></script>
    </head>
    <body>
    <div id="body-container">
        <!-- Work around some values being stored in localStorage wrapped in quotes -->
        <script>
            try {
                var theme = localStorage.getItem('mdbook-theme');
                var sidebar = localStorage.getItem('mdbook-sidebar');

                if (theme.startsWith('"') && theme.endsWith('"')) {
                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
                }

                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
                }
            } catch (e) { }
        </script>

        <!-- Set the theme before any content is loaded, prevents flash -->
        <script>
            var theme;
            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
            if (theme === null || theme === undefined) { theme = default_theme; }
            const html = document.documentElement;
            html.classList.remove('light')
            html.classList.add(theme);
            html.classList.add("js");
        </script>

        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">

        <!-- Hide / unhide sidebar before it is displayed -->
        <script>
            var sidebar = null;
            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
            if (document.body.clientWidth >= 1080) {
                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                sidebar = sidebar || 'visible';
            } else {
                sidebar = 'hidden';
            }
            sidebar_toggle.checked = sidebar === 'visible';
            html.classList.remove('sidebar-visible');
            html.classList.add("sidebar-" + sidebar);
        </script>

        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
            <!-- populated by js -->
            <mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
            <noscript>
                <iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
            </noscript>
            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
                <div class="sidebar-resize-indicator"></div>
            </div>
        </nav>

        <div id="page-wrapper" class="page-wrapper">

            <div class="page">
                <div id="menu-bar-hover-placeholder"></div>
                <div id="menu-bar" class="menu-bar sticky">
                    <div class="left-buttons">
                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                            <i class="fa fa-bars"></i>
                        </label>
                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                            <i class="fa fa-paint-brush"></i>
                        </button>
                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                        </ul>
                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
                            <i class="fa fa-search"></i>
                        </button>
                    </div>

                    <h1 class="menu-title">Notes</h1>

                    <div class="right-buttons">
                        <a href="../print.html" title="Print this book" aria-label="Print this book">
                            <i id="print-button" class="fa fa-print"></i>
                        </a>
                        <a href="https://github.com/johannst/notes" title="Git repository" aria-label="Git repository">
                            <i id="git-repository-button" class="fa fa-github"></i>
                        </a>

                    </div>
                </div>

                <div id="search-wrapper" class="hidden">
                    <form id="searchbar-outer" class="searchbar-outer">
                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
                    </form>
                    <div id="searchresults-outer" class="searchresults-outer hidden">
                        <div id="searchresults-header" class="searchresults-header"></div>
                        <ul id="searchresults">
                        </ul>
                    </div>
                </div>

                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                <script>
                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
                    });
                </script>

                <div id="content" class="content">
                    <main>
                        <h1 id="elf-symbol-versioning"><a class="header" href="#elf-symbol-versioning">ELF Symbol Versioning</a></h1>
<p>The <a href="https://refspecs.linuxbase.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/symversion.html">ELF symbol versioning</a> mechanism allows to attach version
information to symbols.
This can be used to express symbol version requirements or to provide certain
symbols multiple times in the same ELF file with different versions (eg for
backwards compatibility).</p>
<p>The <code>libpthread.so</code> library is an example which provides the
<code>pthread_cond_wait</code> symbol multiple times but in different versions.
With readelf the version of the symbol can be seen after the <code>@</code>.</p>
<pre><code class="language-bash">&gt; readelf -W --dyn-syms /lib/libpthread.so

Symbol table '.dynsym' contains 342 entries:
   Num:    Value  Size Type    Bind   Vis      Ndx Name
   ...
   141: 0000f080   696 FUNC    GLOBAL DEFAULT   16 pthread_cond_wait@@GLIBC_2.3.2
   142: 00010000   111 FUNC    GLOBAL DEFAULT   16 pthread_cond_wait@GLIBC_2.2.5
</code></pre>
<p>The <code>@@</code> denotes the <strong>default symbol version</strong> which will be used during
static linking against the library.
The following dump shows that the <code>tmp</code> program linked against <code>lpthread</code> will
depend on the symbol version <code>GLIBC_2.3.2</code>, which is the default version.</p>
<pre><code class="language-bash">&gt; echo "#include &lt;pthread.h&gt;
        int main() {
          return pthread_cond_wait(0,0);
        }" | gcc -o tmp -xc - -lpthread;
  readelf -W --dyn-syms tmp | grep pthread_cond_wait;

Symbol table '.dynsym' contains 7 entries:
   Num:    Value  Size Type    Bind   Vis      Ndx Name
   ...
     2: 00000000     0 FUNC    GLOBAL DEFAULT  UND pthread_cond_wait@GLIBC_2.3.2 (2)
</code></pre>
<blockquote>
<p>Only <strong>one</strong> symbol can be annotated as the <code>@@</code> default version.</p>
</blockquote>
<p>Using the <code>--version-info</code> flag with readelf, more details on the symbol
version info compiled into the <code>tmp</code> ELF file can be obtained.</p>
<ul>
<li>The <code>.gnu.version</code> section contains the version definition for each symbol in
the <code>.dynsym</code> section. <code>pthread_cond_wait</code> is at index <code>2</code> in the <code>.dynsym</code>
section, the corresponding symbol version is at index <code>2</code> in the
<code>.gnu.version</code> section.</li>
<li>The <code>.gnu.version_r</code> section contains symbol version requirements per shared
library dependency (<code>DT_NEEDED</code> dynamic entry).</li>
</ul>
<pre><code class="language-bash">&gt; readelf -W --version-info --dyn-syms tmp

Symbol table '.dynsym' contains 7 entries:
   Num:    Value          Size Type    Bind   Vis      Ndx Name
     0: 0000000000000000     0 NOTYPE  LOCAL  DEFAULT  UND 
     1: 0000000000000000     0 NOTYPE  WEAK   DEFAULT  UND _ITM_deregisterTMCloneTable
     2: 0000000000000000     0 FUNC    GLOBAL DEFAULT  UND pthread_cond_wait@GLIBC_2.3.2 (2)
     3: 0000000000000000     0 FUNC    GLOBAL DEFAULT  UND __libc_start_main@GLIBC_2.2.5 (3)
     4: 0000000000000000     0 NOTYPE  WEAK   DEFAULT  UND __gmon_start__
     5: 0000000000000000     0 NOTYPE  WEAK   DEFAULT  UND _ITM_registerTMCloneTable
     6: 0000000000000000     0 FUNC    WEAK   DEFAULT  UND __cxa_finalize@GLIBC_2.2.5 (3)

Version symbols section '.gnu.version' contains 7 entries:
 Addr: 0x0000000000000534  Offset: 0x000534  Link: 6 (.dynsym)
  000:   0 (*local*)       0 (*local*)       2 (GLIBC_2.3.2)   3 (GLIBC_2.2.5)
  004:   0 (*local*)       0 (*local*)       3 (GLIBC_2.2.5)

Version needs section '.gnu.version_r' contains 2 entries:
 Addr: 0x0000000000000548  Offset: 0x000548  Link: 7 (.dynstr)
  000000: Version: 1  File: libc.so.6  Cnt: 1
  0x0010:   Name: GLIBC_2.2.5  Flags: none  Version: 3
  0x0020: Version: 1  File: libpthread.so.0  Cnt: 1
  0x0030:   Name: GLIBC_2.3.2  Flags: none  Version: 2
</code></pre>
<p>The gnu dynamic linker allows to inspect the version processing during runtime
by setting the <code>LD_DEBUG</code> environment variable accordingly.</p>
<pre><code class="language-text"># version: Display version dependencies.
&gt; LD_DEBUG=versions ./tmp
    717904: checking for version `GLIBC_2.2.5' in file /usr/lib/libc.so.6 [0] required by file ./tmp [0]
    717904: checking for version `GLIBC_2.3.2' in file /usr/lib/libpthread.so.0 [0] required by file ./tmp [0]
    ...

#  symbols : Display symbol table processing.
#  bindings: Display information about symbol binding.
&gt; LD_DEBUG=symbols,bindings ./tmp
    ...
    718123: symbol=pthread_cond_wait;  lookup in file=./tmp [0]
    718123: symbol=pthread_cond_wait;  lookup in file=/usr/lib/libpthread.so.0 [0]
    718123: binding file ./tmp [0] to /usr/lib/libpthread.so.0 [0]: normal symbol `pthread_cond_wait' [GLIBC_2.3.2]
</code></pre>
<h2 id="example-version-script"><a class="header" href="#example-version-script">Example: version script</a></h2>
<p>The following shows an example C++ library <code>libfoo</code> which provides the same
symbol multiple times but in different versions.</p>
<pre><code class="language-cpp">// file: libfoo.cc
#include&lt;stdio.h&gt;

// Bind function symbols to version nodes.
//
// ..@       -&gt; Is the unversioned symbol.
// ..@@..    -&gt; Is the default symbol.

__asm__(".symver func_v0,func@");
__asm__(".symver func_v1,func@LIB_V1");
__asm__(".symver func_v2,func@@LIB_V2");

extern "C" {
    void func_v0() { puts("func_v0"); }
    void func_v1() { puts("func_v1"); }
    void func_v2() { puts("func_v2"); }
}

__asm__(".symver _Z11func_cpp_v1i,_Z8func_cppi@LIB_V1");
__asm__(".symver _Z11func_cpp_v2i,_Z8func_cppi@@LIB_V2");

void func_cpp_v1(int) { puts("func_cpp_v1"); }
void func_cpp_v2(int) { puts("func_cpp_v2"); }

void func_cpp(int) { puts("func_cpp_v2"); }
</code></pre>
<p>Version script for <code>libfoo</code> which defines which symbols for which versions are
exported from the ELF file.</p>
<pre><code class="language-ld"># file: libfoo.ver
LIB_V1 {
    global:
        func;
        extern "C++" {
            "func_cpp(int)";
        };
    local:
        *;
};

LIB_V2 {
    global:
        func;
        extern "C++" {
            "func_cpp(int)";
        };
} LIB_V1;
</code></pre>
<blockquote>
<p>The <strong>local:</strong> section in <code>LIB_V1</code> is a catch all, that matches any symbol
not explicitly specified, and defines that the symbol is local and therefore
not exported from the ELF file.</p>
</blockquote>
<p>The library <code>libfoo</code> can be linked with the version definitions in <code>libfoo.ver</code>
by passing the version script to the linker with the <code>--version-script</code> flag.</p>
<pre><code class="language-bash">&gt; g++ -shared -fPIC -o libfoo.so libfoo.cc -Wl,--version-script=libfoo.ver
&gt; readelf -W --dyn-syms libfoo.so | c++filt

Symbol table '.dynsym' contains 14 entries:
   Num:    Value          Size Type    Bind   Vis      Ndx Name
   ...
     6: 0000000000000000     0 OBJECT  GLOBAL DEFAULT  ABS LIB_V1
     7: 000000000000114b    29 FUNC    GLOBAL DEFAULT   13 func_cpp(int)@LIB_V1
     8: 0000000000001168    29 FUNC    GLOBAL DEFAULT   13 func_cpp(int)@@LIB_V2
     9: 0000000000001185    29 FUNC    GLOBAL DEFAULT   13 func_cpp(int)@@LIB_V1
    10: 0000000000000000     0 OBJECT  GLOBAL DEFAULT  ABS LIB_V2
    11: 0000000000001109    22 FUNC    GLOBAL DEFAULT   13 func
    12: 000000000000111f    22 FUNC    GLOBAL DEFAULT   13 func@LIB_V1
    13: 0000000000001135    22 FUNC    GLOBAL DEFAULT   13 func@@LIB_V2
</code></pre>
<p>The following program demonstrates how to make use of the different versions:</p>
<pre><code class="language-cpp">// file: main.cc
#include &lt;dlfcn.h&gt;
#include &lt;assert.h&gt;

// Links against default symbol in the lib.so.
extern "C" void func();

int main() {
    // Call the default version.
    func();

#ifdef _GNU_SOURCE
    typedef void (*fnptr)();

    // Unversioned lookup.
    fnptr fn_v0 = (fnptr)dlsym(RTLD_DEFAULT, "func");
    // Version lookup.
    fnptr fn_v1 = (fnptr)dlvsym(RTLD_DEFAULT, "func", "LIB_V1");
    fnptr fn_v2 = (fnptr)dlvsym(RTLD_DEFAULT, "func", "LIB_V2");

    assert(fn_v0 != 0);
    assert(fn_v1 != 0);
    assert(fn_v2 != 0);

    fn_v0();
    fn_v1();
    fn_v2();
#endif

    return 0;
}
</code></pre>
<p>Compiling and running results in:</p>
<pre><code class="language-bash">&gt; g++ -o main main.cc -ldl ./libfoo.so &amp;&amp; ./main
func_v2
func_v0
func_v1
func_v2
</code></pre>
<h2 id="references"><a class="header" href="#references">References</a></h2>
<ul>
<li><a href="https://akkadia.org/drepper/symbol-versioning">ELF Symbol Versioning</a></li>
<li><a href="https://sourceware.org/binutils/docs/ld/VERSION.html">Binutils ld: Symbol Versioning</a></li>
<li><a href="https://refspecs.linuxbase.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/symversion.html">LSB: Symbol Versioning</a></li>
<li><a href="https://akkadia.org/drepper/dsohowto.pdf">How To Write Shared Libraries</a></li>
<li><a href="https://refspecs.linuxbase.org/elf/elf.pdf">LSB: ELF File Format</a></li>
</ul>

                    </main>

                    <nav class="nav-wrapper" aria-label="Page navigation">
                        <!-- Mobile navigation buttons -->
                            <a rel="prev" href="../development/ld.so.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                <i class="fa fa-angle-left"></i>
                            </a>

                            <a rel="next prefetch" href="../development/python.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                <i class="fa fa-angle-right"></i>
                            </a>

                        <div style="clear: both"></div>
                    </nav>
                </div>
            </div>

            <nav class="nav-wide-wrapper" aria-label="Page navigation">
                    <a rel="prev" href="../development/ld.so.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                        <i class="fa fa-angle-left"></i>
                    </a>

                    <a rel="next prefetch" href="../development/python.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                        <i class="fa fa-angle-right"></i>
                    </a>
            </nav>

        </div>


        <script>
            window.playground_copyable = true;
        </script>


        <script src="../elasticlunr.min.js"></script>
        <script src="../mark.min.js"></script>
        <script src="../searcher.js"></script>

        <script src="../clipboard.min.js"></script>
        <script src="../highlight.js"></script>
        <script src="../book.js"></script>

        <!-- Custom JS scripts -->


    </div>
    </body>
</html>
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
    <head>
        <!-- Book generated using mdBook -->
        <meta charset="UTF-8">
        <title>symbol versioning - Notes</title>


        <!-- Custom HTML head -->

        <meta name="description" content="">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="theme-color" content="#ffffff">

        <link rel="icon" href="../favicon.svg">
        <link rel="shortcut icon" href="../favicon.png">
        <link rel="stylesheet" href="../css/variables.css">
        <link rel="stylesheet" href="../css/general.css">
        <link rel="stylesheet" href="../css/chrome.css">
        <link rel="stylesheet" href="../css/print.css" media="print">

        <!-- Fonts -->
        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
        <link rel="stylesheet" href="../fonts/fonts.css">

        <!-- Highlight.js Stylesheets -->
        <link rel="stylesheet" href="../highlight.css">
        <link rel="stylesheet" href="../tomorrow-night.css">
        <link rel="stylesheet" href="../ayu-highlight.css">

        <!-- Custom theme stylesheets -->


        <!-- Provide site root to javascript -->
        <script>
            var path_to_root = "../";
            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
        </script>
        <!-- Start loading toc.js asap -->
        <script src="../toc.js"></script>
    </head>
    <body>
    <div id="body-container">
        <!-- Work around some values being stored in localStorage wrapped in quotes -->
        <script>
            try {
                var theme = localStorage.getItem('mdbook-theme');
                var sidebar = localStorage.getItem('mdbook-sidebar');

                if (theme.startsWith('"') && theme.endsWith('"')) {
                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
                }

                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
                }
            } catch (e) { }
        </script>

        <!-- Set the theme before any content is loaded, prevents flash -->
        <script>
            var theme;
            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
            if (theme === null || theme === undefined) { theme = default_theme; }
            const html = document.documentElement;
            html.classList.remove('light')
            html.classList.add(theme);
            html.classList.add("js");
        </script>

        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">

        <!-- Hide / unhide sidebar before it is displayed -->
        <script>
            var sidebar = null;
            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
            if (document.body.clientWidth >= 1080) {
                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                sidebar = sidebar || 'visible';
            } else {
                sidebar = 'hidden';
            }
            sidebar_toggle.checked = sidebar === 'visible';
            html.classList.remove('sidebar-visible');
            html.classList.add("sidebar-" + sidebar);
        </script>

        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
            <!-- populated by js -->
            <mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
            <noscript>
                <iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
            </noscript>
            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
                <div class="sidebar-resize-indicator"></div>
            </div>
        </nav>

        <div id="page-wrapper" class="page-wrapper">

            <div class="page">
                <div id="menu-bar-hover-placeholder"></div>
                <div id="menu-bar" class="menu-bar sticky">
                    <div class="left-buttons">
                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                            <i class="fa fa-bars"></i>
                        </label>
                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                            <i class="fa fa-paint-brush"></i>
                        </button>
                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                        </ul>
                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
                            <i class="fa fa-search"></i>
                        </button>
                    </div>

                    <h1 class="menu-title">Notes</h1>

                    <div class="right-buttons">
                        <a href="../print.html" title="Print this book" aria-label="Print this book">
                            <i id="print-button" class="fa fa-print"></i>
                        </a>
                        <a href="https://github.com/johannst/notes" title="Git repository" aria-label="Git repository">
                            <i id="git-repository-button" class="fa fa-github"></i>
                        </a>

                    </div>
                </div>

                <div id="search-wrapper" class="hidden">
                    <form id="searchbar-outer" class="searchbar-outer">
                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
                    </form>
                    <div id="searchresults-outer" class="searchresults-outer hidden">
                        <div id="searchresults-header" class="searchresults-header"></div>
                        <ul id="searchresults">
                        </ul>
                    </div>
                </div>

                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                <script>
                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
                    });
                </script>

                <div id="content" class="content">
                    <main>
                        <h1 id="elf-symbol-versioning"><a class="header" href="#elf-symbol-versioning">ELF Symbol Versioning</a></h1>
<p>The <a href="https://refspecs.linuxbase.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/symversion.html">ELF symbol versioning</a> mechanism allows to attach version
information to symbols.
This can be used to express symbol version requirements or to provide certain
symbols multiple times in the same ELF file with different versions (eg for
backwards compatibility).</p>
<p>The <code>libpthread.so</code> library is an example which provides the
<code>pthread_cond_wait</code> symbol multiple times but in different versions.
With readelf the version of the symbol can be seen after the <code>@</code>.</p>
<pre><code class="language-bash">&gt; readelf -W --dyn-syms /lib/libpthread.so

Symbol table '.dynsym' contains 342 entries:
   Num:    Value  Size Type    Bind   Vis      Ndx Name
   ...
   141: 0000f080   696 FUNC    GLOBAL DEFAULT   16 pthread_cond_wait@@GLIBC_2.3.2
   142: 00010000   111 FUNC    GLOBAL DEFAULT   16 pthread_cond_wait@GLIBC_2.2.5
</code></pre>
<p>The <code>@@</code> denotes the <strong>default symbol version</strong> which will be used during
static linking against the library.
The following dump shows that the <code>tmp</code> program linked against <code>lpthread</code> will
depend on the symbol version <code>GLIBC_2.3.2</code>, which is the default version.</p>
<pre><code class="language-bash">&gt; echo "#include &lt;pthread.h&gt;
        int main() {
          return pthread_cond_wait(0,0);
        }" | gcc -o tmp -xc - -lpthread;
  readelf -W --dyn-syms tmp | grep pthread_cond_wait;

Symbol table '.dynsym' contains 7 entries:
   Num:    Value  Size Type    Bind   Vis      Ndx Name
   ...
     2: 00000000     0 FUNC    GLOBAL DEFAULT  UND pthread_cond_wait@GLIBC_2.3.2 (2)
</code></pre>
<blockquote>
<p>Only <strong>one</strong> symbol can be annotated as the <code>@@</code> default version.</p>
</blockquote>
<p>Using the <code>--version-info</code> flag with readelf, more details on the symbol
version info compiled into the <code>tmp</code> ELF file can be obtained.</p>
<ul>
<li>The <code>.gnu.version</code> section contains the version definition for each symbol in
the <code>.dynsym</code> section. <code>pthread_cond_wait</code> is at index <code>2</code> in the <code>.dynsym</code>
section, the corresponding symbol version is at index <code>2</code> in the
<code>.gnu.version</code> section.</li>
<li>The <code>.gnu.version_r</code> section contains symbol version requirements per shared
library dependency (<code>DT_NEEDED</code> dynamic entry).</li>
</ul>
<pre><code class="language-bash">&gt; readelf -W --version-info --dyn-syms tmp

Symbol table '.dynsym' contains 7 entries:
   Num:    Value          Size Type    Bind   Vis      Ndx Name
     0: 0000000000000000     0 NOTYPE  LOCAL  DEFAULT  UND 
     1: 0000000000000000     0 NOTYPE  WEAK   DEFAULT  UND _ITM_deregisterTMCloneTable
     2: 0000000000000000     0 FUNC    GLOBAL DEFAULT  UND pthread_cond_wait@GLIBC_2.3.2 (2)
     3: 0000000000000000     0 FUNC    GLOBAL DEFAULT  UND __libc_start_main@GLIBC_2.2.5 (3)
     4: 0000000000000000     0 NOTYPE  WEAK   DEFAULT  UND __gmon_start__
     5: 0000000000000000     0 NOTYPE  WEAK   DEFAULT  UND _ITM_registerTMCloneTable
     6: 0000000000000000     0 FUNC    WEAK   DEFAULT  UND __cxa_finalize@GLIBC_2.2.5 (3)

Version symbols section '.gnu.version' contains 7 entries:
 Addr: 0x0000000000000534  Offset: 0x000534  Link: 6 (.dynsym)
  000:   0 (*local*)       0 (*local*)       2 (GLIBC_2.3.2)   3 (GLIBC_2.2.5)
  004:   0 (*local*)       0 (*local*)       3 (GLIBC_2.2.5)

Version needs section '.gnu.version_r' contains 2 entries:
 Addr: 0x0000000000000548  Offset: 0x000548  Link: 7 (.dynstr)
  000000: Version: 1  File: libc.so.6  Cnt: 1
  0x0010:   Name: GLIBC_2.2.5  Flags: none  Version: 3
  0x0020: Version: 1  File: libpthread.so.0  Cnt: 1
  0x0030:   Name: GLIBC_2.3.2  Flags: none  Version: 2
</code></pre>
<p>The gnu dynamic linker allows to inspect the version processing during runtime
by setting the <code>LD_DEBUG</code> environment variable accordingly.</p>
<pre><code class="language-text"># version: Display version dependencies.
&gt; LD_DEBUG=versions ./tmp
    717904: checking for version `GLIBC_2.2.5' in file /usr/lib/libc.so.6 [0] required by file ./tmp [0]
    717904: checking for version `GLIBC_2.3.2' in file /usr/lib/libpthread.so.0 [0] required by file ./tmp [0]
    ...

#  symbols : Display symbol table processing.
#  bindings: Display information about symbol binding.
&gt; LD_DEBUG=symbols,bindings ./tmp
    ...
    718123: symbol=pthread_cond_wait;  lookup in file=./tmp [0]
    718123: symbol=pthread_cond_wait;  lookup in file=/usr/lib/libpthread.so.0 [0]
    718123: binding file ./tmp [0] to /usr/lib/libpthread.so.0 [0]: normal symbol `pthread_cond_wait' [GLIBC_2.3.2]
</code></pre>
<h2 id="example-version-script"><a class="header" href="#example-version-script">Example: version script</a></h2>
<p>The following shows an example C++ library <code>libfoo</code> which provides the same
symbol multiple times but in different versions.</p>
<pre><code class="language-cpp">// file: libfoo.cc
#include&lt;stdio.h&gt;

// Bind function symbols to version nodes.
//
// ..@       -&gt; Is the unversioned symbol.
// ..@@..    -&gt; Is the default symbol.

__asm__(".symver func_v0,func@");
__asm__(".symver func_v1,func@LIB_V1");
__asm__(".symver func_v2,func@@LIB_V2");

extern "C" {
    void func_v0() { puts("func_v0"); }
    void func_v1() { puts("func_v1"); }
    void func_v2() { puts("func_v2"); }
}

__asm__(".symver _Z11func_cpp_v1i,_Z8func_cppi@LIB_V1");
__asm__(".symver _Z11func_cpp_v2i,_Z8func_cppi@@LIB_V2");

void func_cpp_v1(int) { puts("func_cpp_v1"); }
void func_cpp_v2(int) { puts("func_cpp_v2"); }

void func_cpp(int) { puts("func_cpp_v2"); }
</code></pre>
<p>Version script for <code>libfoo</code> which defines which symbols for which versions are
exported from the ELF file.</p>
<pre><code class="language-ld"># file: libfoo.ver
LIB_V1 {
    global:
        func;
        extern "C++" {
            "func_cpp(int)";
        };
    local:
        *;
};

LIB_V2 {
    global:
        func;
        extern "C++" {
            "func_cpp(int)";
        };
} LIB_V1;
</code></pre>
<blockquote>
<p>The <strong>local:</strong> section in <code>LIB_V1</code> is a catch all, that matches any symbol
not explicitly specified, and defines that the symbol is local and therefore
not exported from the ELF file.</p>
</blockquote>
<p>The library <code>libfoo</code> can be linked with the version definitions in <code>libfoo.ver</code>
by passing the version script to the linker with the <code>--version-script</code> flag.</p>
<pre><code class="language-bash">&gt; g++ -shared -fPIC -o libfoo.so libfoo.cc -Wl,--version-script=libfoo.ver
&gt; readelf -W --dyn-syms libfoo.so | c++filt

Symbol table '.dynsym' contains 14 entries:
   Num:    Value          Size Type    Bind   Vis      Ndx Name
   ...
     6: 0000000000000000     0 OBJECT  GLOBAL DEFAULT  ABS LIB_V1
     7: 000000000000114b    29 FUNC    GLOBAL DEFAULT   13 func_cpp(int)@LIB_V1
     8: 0000000000001168    29 FUNC    GLOBAL DEFAULT   13 func_cpp(int)@@LIB_V2
     9: 0000000000001185    29 FUNC    GLOBAL DEFAULT   13 func_cpp(int)@@LIB_V1
    10: 0000000000000000     0 OBJECT  GLOBAL DEFAULT  ABS LIB_V2
    11: 0000000000001109    22 FUNC    GLOBAL DEFAULT   13 func
    12: 000000000000111f    22 FUNC    GLOBAL DEFAULT   13 func@LIB_V1
    13: 0000000000001135    22 FUNC    GLOBAL DEFAULT   13 func@@LIB_V2
</code></pre>
<p>The following program demonstrates how to make use of the different versions:</p>
<pre><code class="language-cpp">// file: main.cc
#include &lt;dlfcn.h&gt;
#include &lt;assert.h&gt;

// Links against default symbol in the lib.so.
extern "C" void func();

int main() {
    // Call the default version.
    func();

#ifdef _GNU_SOURCE
    typedef void (*fnptr)();

    // Unversioned lookup.
    fnptr fn_v0 = (fnptr)dlsym(RTLD_DEFAULT, "func");
    // Version lookup.
    fnptr fn_v1 = (fnptr)dlvsym(RTLD_DEFAULT, "func", "LIB_V1");
    fnptr fn_v2 = (fnptr)dlvsym(RTLD_DEFAULT, "func", "LIB_V2");

    assert(fn_v0 != 0);
    assert(fn_v1 != 0);
    assert(fn_v2 != 0);

    fn_v0();
    fn_v1();
    fn_v2();
#endif

    return 0;
}
</code></pre>
<p>Compiling and running results in:</p>
<pre><code class="language-bash">&gt; g++ -o main main.cc -ldl ./libfoo.so &amp;&amp; ./main
func_v2
func_v0
func_v1
func_v2
</code></pre>
<h2 id="references"><a class="header" href="#references">References</a></h2>
<ul>
<li><a href="https://akkadia.org/drepper/symbol-versioning">ELF Symbol Versioning</a></li>
<li><a href="https://sourceware.org/binutils/docs/ld/VERSION.html">Binutils ld: Symbol Versioning</a></li>
<li><a href="https://refspecs.linuxbase.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/symversion.html">LSB: Symbol Versioning</a></li>
<li><a href="https://akkadia.org/drepper/dsohowto.pdf">How To Write Shared Libraries</a></li>
<li><a href="https://refspecs.linuxbase.org/elf/elf.pdf">LSB: ELF File Format</a></li>
</ul>

                    </main>

                    <nav class="nav-wrapper" aria-label="Page navigation">
                        <!-- Mobile navigation buttons -->
                            <a rel="prev" href="../development/ld.so.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                <i class="fa fa-angle-left"></i>
                            </a>

                            <a rel="next prefetch" href="../development/python.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                <i class="fa fa-angle-right"></i>
                            </a>

                        <div style="clear: both"></div>
                    </nav>
                </div>
            </div>

            <nav class="nav-wide-wrapper" aria-label="Page navigation">
                    <a rel="prev" href="../development/ld.so.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                        <i class="fa fa-angle-left"></i>
                    </a>

                    <a rel="next prefetch" href="../development/python.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                        <i class="fa fa-angle-right"></i>
                    </a>
            </nav>

        </div>


        <script>
            window.playground_copyable = true;
        </script>


        <script src="../elasticlunr.min.js"></script>
        <script src="../mark.min.js"></script>
        <script src="../searcher.js"></script>

        <script src="../clipboard.min.js"></script>
        <script src="../highlight.js"></script>
        <script src="../book.js"></script>

        <!-- Custom JS scripts -->


    </div>
    </body>
</html>