/usr/share/doc/clang-6.0-doc/html/LTOVisibility.html is in clang-6.0-doc 1:6.0-1ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>LTO Visibility — Clang 6 documentation</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="SafeStack" href="SafeStack.html" />
<link rel="prev" title="Control Flow Integrity Design Documentation" href="ControlFlowIntegrityDesign.html" />
</head>
<body>
<div class="header" role="banner"><h1 class="heading"><a href="index.html">
<span>Clang 6 documentation</span></a></h1>
<h2 class="heading"><span>LTO Visibility</span></h2>
</div>
<div class="topnav" role="navigation" aria-label="top navigation">
<p>
«  <a href="ControlFlowIntegrityDesign.html">Control Flow Integrity Design Documentation</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="SafeStack.html">SafeStack</a>  »
</p>
</div>
<div class="content">
<div class="section" id="lto-visibility">
<h1>LTO Visibility<a class="headerlink" href="#lto-visibility" title="Permalink to this headline">¶</a></h1>
<p><em>LTO visibility</em> is a property of an entity that specifies whether it can be
referenced from outside the current LTO unit. A <em>linkage unit</em> is a set of
translation units linked together into an executable or DSO, and a linkage
unit’s <em>LTO unit</em> is the subset of the linkage unit that is linked together
using link-time optimization; in the case where LTO is not being used, the
linkage unit’s LTO unit is empty. Each linkage unit has only a single LTO unit.</p>
<p>The LTO visibility of a class is used by the compiler to determine which
classes the whole-program devirtualization (<code class="docutils literal"><span class="pre">-fwhole-program-vtables</span></code>) and
control flow integrity (<code class="docutils literal"><span class="pre">-fsanitize=cfi-vcall</span></code>) features apply to. These
features use whole-program information, so they require the entire class
hierarchy to be visible in order to work correctly.</p>
<p>If any translation unit in the program uses either of the whole-program
devirtualization or control flow integrity features, it is effectively an ODR
violation to define a class with hidden LTO visibility in multiple linkage
units. A class with public LTO visibility may be defined in multiple linkage
units, but the tradeoff is that the whole-program devirtualization and
control flow integrity features can only be applied to classes with hidden LTO
visibility. A class’s LTO visibility is treated as an ODR-relevant property
of its definition, so it must be consistent between translation units.</p>
<p>In translation units built with LTO, LTO visibility is based on the
class’s symbol visibility as expressed at the source level (i.e. the
<code class="docutils literal"><span class="pre">__attribute__((visibility("...")))</span></code> attribute, or the <code class="docutils literal"><span class="pre">-fvisibility=</span></code>
flag) or, on the Windows platform, the dllimport and dllexport attributes. When
targeting non-Windows platforms, classes with a visibility other than hidden
visibility receive public LTO visibility. When targeting Windows, classes
with dllimport or dllexport attributes receive public LTO visibility. All
other classes receive hidden LTO visibility. Classes with internal linkage
(e.g. classes declared in unnamed namespaces) also receive hidden LTO
visibility.</p>
<p>A class defined in a translation unit built without LTO receives public
LTO visibility regardless of its object file visibility, linkage or other
attributes.</p>
<p>This mechanism will produce the correct result in most cases, but there are
two cases where it may wrongly infer hidden LTO visibility.</p>
<ol class="arabic simple">
<li>As a corollary of the above rules, if a linkage unit is produced from a
combination of LTO object files and non-LTO object files, any hidden
visibility class defined in both a translation unit built with LTO and
a translation unit built without LTO must be defined with public LTO
visibility in order to avoid an ODR violation.</li>
<li>Some ABIs provide the ability to define an abstract base class without
visibility attributes in multiple linkage units and have virtual calls
to derived classes in other linkage units work correctly. One example of
this is COM on Windows platforms. If the ABI allows this, any base class
used in this way must be defined with public LTO visibility.</li>
</ol>
<p>Classes that fall into either of these categories can be marked up with the
<code class="docutils literal"><span class="pre">[[clang::lto_visibility_public]]</span></code> attribute. To specifically handle the
COM case, classes with the <code class="docutils literal"><span class="pre">__declspec(uuid())</span></code> attribute receive public
LTO visibility. On Windows platforms, clang-cl’s <code class="docutils literal"><span class="pre">/MT</span></code> and <code class="docutils literal"><span class="pre">/MTd</span></code>
flags statically link the program against a prebuilt standard library;
these flags imply public LTO visibility for every class declared in the
<code class="docutils literal"><span class="pre">std</span></code> and <code class="docutils literal"><span class="pre">stdext</span></code> namespaces.</p>
<div class="section" id="example">
<h2>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
<p>The following example shows how LTO visibility works in practice in several
cases involving two linkage units, <code class="docutils literal"><span class="pre">main</span></code> and <code class="docutils literal"><span class="pre">dso.so</span></code>.</p>
<div class="highlight-none"><div class="highlight"><pre><span></span>+-----------------------------------------------------------+ +----------------------------------------------------+
| main (clang++ -fvisibility=hidden): | | dso.so (clang++ -fvisibility=hidden): |
| | | |
| +-----------------------------------------------------+ | | struct __attribute__((visibility("default"))) C { |
| | LTO unit (clang++ -fvisibility=hidden -flto): | | | virtual void f(); |
| | | | | } |
| | struct A { ... }; | | | void C::f() {} |
| | struct [[clang::lto_visibility_public]] B { ... }; | | | struct D { |
| | struct __attribute__((visibility("default"))) C { | | | virtual void g() = 0; |
| | virtual void f(); | | | }; |
| | }; | | | struct E : D { |
| | struct [[clang::lto_visibility_public]] D { | | | virtual void g() { ... } |
| | virtual void g() = 0; | | | }; |
| | }; | | | __attribute__(visibility("default"))) D *mkE() { |
| | | | | return new E; |
| +-----------------------------------------------------+ | | } |
| | | |
| struct B { ... }; | +----------------------------------------------------+
| |
+-----------------------------------------------------------+
</pre></div>
</div>
<p>We will now describe the LTO visibility of each of the classes defined in
these linkage units.</p>
<p>Class <code class="docutils literal"><span class="pre">A</span></code> is not defined outside of <code class="docutils literal"><span class="pre">main</span></code>’s LTO unit, so it can have
hidden LTO visibility. This is inferred from the object file visibility
specified on the command line.</p>
<p>Class <code class="docutils literal"><span class="pre">B</span></code> is defined in <code class="docutils literal"><span class="pre">main</span></code>, both inside and outside its LTO unit. The
definition outside the LTO unit has public LTO visibility, so the definition
inside the LTO unit must also have public LTO visibility in order to avoid
an ODR violation.</p>
<p>Class <code class="docutils literal"><span class="pre">C</span></code> is defined in both <code class="docutils literal"><span class="pre">main</span></code> and <code class="docutils literal"><span class="pre">dso.so</span></code> and therefore must
have public LTO visibility. This is correctly inferred from the <code class="docutils literal"><span class="pre">visibility</span></code>
attribute.</p>
<p>Class <code class="docutils literal"><span class="pre">D</span></code> is an abstract base class with a derived class <code class="docutils literal"><span class="pre">E</span></code> defined
in <code class="docutils literal"><span class="pre">dso.so</span></code>. This is an example of the COM scenario; the definition of
<code class="docutils literal"><span class="pre">D</span></code> in <code class="docutils literal"><span class="pre">main</span></code>’s LTO unit must have public LTO visibility in order to be
compatible with the definition of <code class="docutils literal"><span class="pre">D</span></code> in <code class="docutils literal"><span class="pre">dso.so</span></code>, which is observable
by calling the function <code class="docutils literal"><span class="pre">mkE</span></code>.</p>
</div>
</div>
</div>
<div class="bottomnav" role="navigation" aria-label="bottom navigation">
<p>
«  <a href="ControlFlowIntegrityDesign.html">Control Flow Integrity Design Documentation</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="SafeStack.html">SafeStack</a>  »
</p>
</div>
<div class="footer" role="contentinfo">
© Copyright 2007-2018, The Clang Team.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.7.
</div>
</body>
</html>
|