[BACK]Return to elf.html CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / htdocs / docs

Annotation of htdocs/docs/elf.html, Revision 1.55

1.17      jym         1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
1.1       dsieger     2: <html>
                      3: <head>
                      4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
                      5: <meta name="generator" content="Website XSL Stylesheet V2.6.0">
                      6: <link rel="home" href="../." title="Welcome to The NetBSD Project: Of course it runs NetBSD.">
                      7: <link rel="up" href="../docs/." title="NetBSD Documentation">
                      8: <link rel="previous" href="../docs/compat.html" title="NetBSD Binary Emulation">
1.10      dsieger     9: <link rel="next" href="../docs/encrypted-iscsi.html" title="Encrypted iSCSI Devices on NetBSD">
1.1       dsieger    10: <link rel="first" href="../docs/Hardware/." title="Hardware Documentation">
                     11: <link rel="last" href="../docs/x/." title="NetBSD Documentation: The X Window System">
1.10      dsieger    12: <link rel="stylesheet" href="../global.css" type="text/css">
1.1       dsieger    13:
                     14:
                     15:
                     16:
                     17:   <title>NetBSD ELF FAQ</title>
                     18: </head>
                     19: <body class="website"><div class="webpage">
1.52      maya       20: <a name="docs-elf"></a><div id="top"><a href="#mainContent" id="skiplink" tabindex="1">Skip to main content.</a></div>
1.35      maya       21: <div id="centralHeader"><div id="logo">
1.21      jym        22: <a href="../"><img alt="[NetBSD Logo]" src="../images/NetBSD-smaller.png"></a><div id="name"><a href="../">
1.19      jym        23:          The NetBSD Project
1.21      jym        24:        </a></div>
                     25: <div id="slogan"><a href="../">
1.19      jym        26:          &#8220;Of course it runs NetBSD&#8221;
1.21      jym        27:        </a></div>
1.35      maya       28: </div></div>
1.36      maya       29: <input id="hamburger" type="checkbox"><label class="menuicon" for="hamburger"><span></span></label><div id="navBar" role="navigation">
1.6       dsieger    30: <span class="doNotDisplay">
                     31:          Navigation:
1.17      jym        32:        </span><ul>
                     33: <li><a href="../">
                     34:          Home</a></li>
                     35: <li>
                     36: <a href="../">
1.20      wiz        37:          News &amp; Media</a><ul>
1.17      jym        38: <li><a href="../changes/">
                     39:            Recent changes</a></li>
1.38      maya       40: <li><a href="//blog.NetBSD.org/">
1.17      jym        41:            NetBSD blog</a></li>
                     42: <li><a href="../gallery/events.html">
                     43:            Events</a></li>
                     44: </ul>
                     45: </li>
                     46: <li>
                     47: <a href="../about/">
                     48:          About</a><ul>
                     49: <li><a href="../about/">
                     50:            NetBSD</a></li>
1.47      maya       51: <li><a href="../people/developers.html">
                     52:            NetBSD developers</a></li>
1.17      jym        53: <li><a href="../gallery/">
                     54:            Advocacy</a></li>
                     55: </ul>
                     56: </li>
                     57: <li>
                     58: <a href="../docs/">
                     59:          Documentation</a><ul>
                     60: <li><a href="../docs/misc/index.html">
                     61:            FAQ &amp; HOWTOs</a></li>
                     62: <li><a href="../docs/guide/en/">
                     63:            The Guide</a></li>
1.39      maya       64: <li><a href="http://man.NetBSD.org/">
1.17      jym        65:            Manual pages</a></li>
1.38      maya       66: <li><a href="//wiki.NetBSD.org/">
1.17      jym        67:            Wiki</a></li>
                     68: </ul>
                     69: </li>
                     70: <li>
                     71: <a href="../support/">
                     72:          Support</a><ul>
                     73: <li><a href="../support/send-pr.html">
                     74:            Problem report guide</a></li>
                     75: <li><a href="../cgi-bin/sendpr.cgi?gndb=netbsd">
                     76:            Report a bug</a></li>
                     77: <li><a href="../support/query-pr.html">
                     78:            Query bug database</a></li>
                     79: <li><a href="../support/security/">
                     80:            Security</a></li>
                     81: </ul>
                     82: </li>
                     83: <li>
                     84: <a href="../community/">
                     85:          Community</a><ul>
1.43      leot       86: <li><a href="//blog.NetBSD.org/">
                     87:            Blog</a></li>
1.17      jym        88: <li><a href="../mailinglists/">
                     89:            Mailing lists</a></li>
1.38      maya       90: <li><a href="//mail-index.NetBSD.org/">
1.17      jym        91:            List archives</a></li>
                     92: </ul>
                     93: </li>
                     94: <li>
                     95: <a href="../developers/">
                     96:          Developers</a><ul>
1.41      maya       97: <li><a href="http://cvsweb.NetBSD.org/">
1.17      jym        98:            Browse source</a></li>
1.38      maya       99: <li><a href="//nxr.NetBSD.org/">
1.17      jym       100:            Cross-reference</a></li>
1.38      maya      101: <li><a href="//releng.NetBSD.org/">
1.17      jym       102:            Release engineering</a></li>
1.38      maya      103: <li><a href="//wiki.NetBSD.org/projects/">
1.17      jym       104:            Projects list</a></li>
                    105: </ul>
                    106: </li>
                    107: <li>
                    108: <a href="../ports/">
                    109:          Ports</a><ul>
                    110: <li><a href="../ports/history.html">
                    111:            History</a></li>
                    112: <li><a href="../ports/emulators.html">
                    113:            Emulators</a></li>
                    114: </ul>
                    115: </li>
                    116: <li>
1.38      maya      117: <a href="//www.pkgsrc.org/">
1.17      jym       118:          Packages</a><ul>
1.39      maya      119: <li><a href="http://www.pkgsrc.se/">
1.17      jym       120:            Browse packages</a></li>
1.38      maya      121: <li><a href="//releng.NetBSD.org/index-pkgsrc.html">
1.17      jym       122:            Release engineering</a></li>
                    123: </ul>
                    124: </li>
                    125: </ul>
1.3       dsieger   126: </div>
1.51      maya      127: <div id="content"><div id="mainContent" class="fullWidth"><div class="rowOfBoxes">
1.3       dsieger   128: <h1>NetBSD ELF FAQ</h1>
1.1       dsieger   129: <h3 class="title"><a name="elf-issues">ELF Issues</a></h3>
                    130: <ul>
                    131: <li><a href="#elf-whatis">What is ELF?</a></li>
                    132: <li><a href="#elf-dynamic-callbacks">A dynamically loaded module at run-time couldn't find symbols
                    133:        from my program image.</a></li>
                    134: <li><a href="#elf-ldconfig">No need for ldconfig or for
                    135:        ld.so.conf!</a></li>
                    136: <li><a href="#elf-rpath">My program can't find its shared library</a></li>
                    137: <li><a href="#elf-examples">Elf Shared Library Examples</a></li>
                    138: <li><a href="#elf-ldconfig-revisited">But I Want ldconfig! I Want ld.so.conf!  I want it! I want it! I want it!</a></li>
                    139: <li><a href="#elf-how-to-tell">How do I tell if my system is ELF?</a></li>
                    140: </ul>
                    141: <hr>
                    142: <h3 class="title">ELF Issues</h3>
                    143:       <h4 class="title">
1.48      maya      144: <a name="elf-whatis"></a>What is ELF?</h4>
1.1       dsieger   145:
                    146:       <p>ELF is a binary format designed to support dynamic objects
                    147:        and shared libraries. On older COFF and ECOFF systems, dynamic
                    148:        support and shared libraries were not naturally supported by the
                    149:        underlying format, leading to dynamic implementations that were
                    150:        at times complex, quirky, and slow.</p>
                    151:
                    152:       <h4 class="title">
                    153: <a name="elf-dynamic-callbacks"></a>A dynamically loaded module at run-time couldn't find symbols
1.48      maya      154:        from my program image.</h4>
1.1       dsieger   155:
                    156:       <p>You probably left off the
                    157:        <span class="bold"><strong>--export-dynamic</strong></span> option when
                    158:        linking the application. This is required only if arbitrary symbols
                    159:        in the program might be needed by the dynamically loaded module,
                    160:        for example, if a program intends to make run-time decisions to
                    161:        dynamically load modules it was never linked with. Note, when
1.55    ! leot      162:        running <a href="http://netbsd.gw.com/cgi-bin/man-cgi?cc+1.i386+NetBSD-8.1">cc(1)</a> instead of <a href="http://netbsd.gw.com/cgi-bin/man-cgi?ld+1.i386+NetBSD-8.1">ld(1)</a> this will be specified
1.1       dsieger   163:        as <span class="bold"><strong>-Wl,--export-dynamic</strong></span>.</p>
                    164:
                    165:       <h4 class="title">
                    166: <a name="elf-ldconfig"></a>No need for ldconfig or for
1.48      maya      167:        <code class="filename">ld.so.conf</code>!</h4>
1.1       dsieger   168:
                    169:       <p>Ideally, there is no need for ldconfig or for
                    170:        <code class="filename">/etc/ld.so.conf</code>,
                    171:        since ELF provides good and predictable (read portable) mechanism
                    172:        to locate shared libraries. Unfortunately there are still a few
                    173:        corner cases (like wanting to run setuid binaries that you don't
                    174:        have the source for, that want shared libraries to be installed
                    175:        somewhere you don't like). For those corner cases, you'll find that
                    176:        creating an <code class="filename">/etc/ld.so.conf</code> file, will
                    177:        still work. Read on though
                    178:        about other ways of doing this and why it is not a good idea. The
                    179:        next section discusses the ELF mechanisms for locating shared
                    180:        libraries.</p>
                    181:
                    182:       <h4 class="title">
1.48      maya      183: <a name="elf-rpath"></a>My program can't find its shared library</h4>
1.1       dsieger   184:
                    185:       <p>An ELF program needs to know the <span class="emphasis"><em>directory</em></span>
1.55    ! leot      186:        and the <span class="emphasis"><em>filename</em></span> required to <a href="http://netbsd.gw.com/cgi-bin/man-cgi?mmap+2.i386+NetBSD-8.1">mmap(2)</a>
1.1       dsieger   187:        its shared libraries. Encoded within the file name is version
                    188:        information. There are one set of mechanisms for the directories
                    189:        and a different mechanism for the file names.</p>
                    190:
1.23      tron      191:       <div class="sect4">
1.1       dsieger   192: <div class="titlepage"><div><div><h5 class="title">
                    193: <a name="elf-rpath-dir"></a>Directories</h5></div></div></div>
                    194:
                    195:
                    196:        <p>Although rarely used, the optional
                    197:          <code class="code">LD_LIBRARY_PATH</code> environment variable specifies
                    198:          a colon-separated search path. This can be used in wrapper
                    199:          scripts as needed for misconfigured applications. It is
                    200:          <span class="emphasis"><em>ignored</em></span> for setuid binaries.</p>
                    201:
                    202:        <p>There is a built-in search path in the run-time loader:
                    203:          <code class="filename">ld.elf_so</code>. On many systems this path
                    204:          consists only of <code class="filename">/usr/lib</code>; although on
                    205:          NetBSD versions prior to 1.4 it also searched
                    206:          <code class="filename">/usr/local/lib</code>.</p>
                    207:
                    208:        <p>The primary directory locating mechanism is the ``rpath''
                    209:          search list contained within the executable image. This search
                    210:          list is set with the <span class="bold"><strong>-R</strong></span>
1.55    ! leot      211:          directive to <a href="http://netbsd.gw.com/cgi-bin/man-cgi?ld+1.i386+NetBSD-8.1">ld(1)</a>. The POSIX syntax for passing
        !           212:          <a href="http://netbsd.gw.com/cgi-bin/man-cgi?ld+1.i386+NetBSD-8.1">ld(1)</a> options through the compiler front end is:</p>
1.1       dsieger   213:
                    214:        <p>&nbsp;&nbsp;&nbsp;&nbsp;<span class="bold"><strong>-Wl,</strong></span>
                    215:          <span class="emphasis"><em>option,option,...</em></span></p>
                    216:
                    217:        <p>For example: <code class="code">-Wl,-R/usr/something/lib</code>.
                    218:          Multiple <span class="bold"><strong>-R</strong></span> directives can be
                    219:          given to a single application to create a shared library
                    220:          search path.</p>
                    221:
                    222:        <p>This directive is also known as
                    223:          <span class="bold"><strong>-rpath</strong></span>. Using
                    224:          <span class="bold"><strong>-R</strong></span> has the advantage of
                    225:          working in older versions of NetBSD as well.</p>
                    226:       </div>
                    227:
1.23      tron      228:       <div class="sect4">
1.1       dsieger   229: <div class="titlepage"><div><div><h5 class="title">
                    230: <a name="elf-rpath-versions"></a>File Names and Versions</h5></div></div></div>
                    231:
                    232:
                    233:        <p>When shared libraries are created, the <span class="bold"><strong>-soname</strong></span> directive is used to record
                    234:          the major version number of the library in the internal
                    235:          <code class="code">DT_SONAME</code> field. The actual library is installed
                    236:          as, for example,</p>
                    237:
1.23      tron      238:          <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1.14      spz       239: <li class="listitem">
1.1       dsieger   240: <code class="filename">libgizmo.so.4.2</code>
                    241:              &nbsp;&nbsp;<span class="emphasis"><em>(the actual file)</em></span>
                    242: </li>
1.14      spz       243: <li class="listitem">
1.1       dsieger   244: <code class="filename">libgizmo.so.4</code>
                    245:              &nbsp;&nbsp;<span class="emphasis"><em>(symbolic link)</em></span>
                    246: </li>
1.14      spz       247: <li class="listitem">
1.1       dsieger   248: <code class="filename">libgizmo.so</code>
                    249:              &nbsp;&nbsp;<span class="emphasis"><em>(symbolic link)</em></span>
                    250: </li>
                    251: </ul></div>
                    252:
                    253:        <p>The idea is that Makefiles will want to link against only
                    254:          the plain .so file. (Who would want to go around changing all
                    255:          the Makefiles just because a new library version was
                    256:          installed?) Once linked, however, the program
                    257:          <span class="emphasis"><em>does</em></span> want to be aware of the major
                    258:          version but does <span class="emphasis"><em>not</em></span> want to deal
                    259:          with the minor version.</p>
                    260:
                    261:        <p>Consequently, the library itself knows that it is
                    262:          <code class="filename">libgizmo.so.4</code> because a <span class="bold"><strong>-soname <code class="filename">libgizmo.so.4</code></strong></span>
                    263:          directive was used when it was created. The program knows
                    264:          it got major version 4 because the linker copied the
                    265:          <code class="filename">libgizmo.so.4</code> <code class="code">DT_SONAME</code> string
                    266:          out of the library and saved it in the executable.</p>
                    267:
                    268:        <p>You don't say <span class="bold"><strong>-soname <code class="filename">libgizmo.so</code></strong></span>,
                    269:          because then the program would use the latest major number
                    270:          and would break if that ever changed. (The major number only
                    271:          changes if the new library is incompatible.)
                    272:          You don't say <span class="bold"><strong>-soname <code class="filename">libgizmo.so.4.2</code></strong></span>,
                    273:          because then the installation of a compatible change that
                    274:          bumps the minor number would unnecessarily break the linked
                    275:          images.</p>
                    276:       </div>
                    277:
                    278:       <h4 class="title">
1.48      maya      279: <a name="elf-examples"></a>Elf Shared Library Examples</h4>
1.1       dsieger   280:
                    281:       <p>To compile <code class="filename">f.c</code> and make an installable
                    282:        shared library out of it:</p>
                    283:
                    284:        <pre class="programlisting">cc -O  -Werror  -c -fpic -DPIC f.c -o f.so
                    285: ar cq libf_pic.a `NM=nm lorder f.so | tsort -q`
                    286: ld -x -shared -R/my/directory/lib -soname libf.so.4 -o \
                    287: &nbsp;&nbsp;&nbsp;libf.so.4.9  /usr/lib/crtbeginS.o  --whole-archive \
                    288: &nbsp;&nbsp;&nbsp;libf_pic.a /usr/lib/crtendS.o</pre>
                    289:
                    290:       <p>There is another way:</p>
                    291:
                    292:       <pre class="programlisting">% cat Makefile
                    293: LIB=f
                    294: SRCS=f.c
                    295: .include &lt;bsd.lib.mk&gt;
                    296: % cat shlib_version
                    297: major=4
                    298: minor=9
                    299: % make
                    300:
                    301: You can disable some of the <code class="code">Makefile</code> targets with NOPROFILE=1 and NOSTATICLIB=1.</pre>
                    302:
                    303:       <p>And there is <span class="emphasis"><em>another</em></span> way:</p>
                    304:
                    305:       <div class="blockquote"><blockquote class="blockquote">
                    306: <code class="code">libtool</code> -
                    307:        The <code class="code">libtool</code> package is a large shell script used to
                    308:        manage shared and static libraries in a platform-independent fashion.
1.42      maya      309:        There is a NetBSD <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/libtool/README.html" target="_top"><code class="filename">devel/libtool</code></a> package
1.10      dsieger   310:        and even a <a class="ulink" href="http://www.gnu.org/software/libtool/libtool.html" target="_top">
1.1       dsieger   311:        <code class="code">libtool</code> home page</a>.
                    312:       </blockquote></div>
                    313:
                    314:       <h4 class="title">
1.48      maya      315: <a name="elf-ldconfig-revisited"></a>But I Want ldconfig! &nbsp;&nbsp;&nbsp;I Want ld.so.conf!  I want it! I want it! I want it!</h4>
1.1       dsieger   316:
                    317:       <p>At first glance, it might seem reasonable, why shouldn't
                    318:        people be able to move things around to anywhere they want and
                    319:        correct the consequent lossage in a
                    320:        <code class="filename">/etc</code> file?</p>
                    321:
                    322:       <p>In fact, some developers of ELF systems have apparently
                    323:        added such a file, but with mixed results. The ELF mechanism
                    324:        was designed to correct some of the previous problems, and
                    325:        introducing the old mechanism would bring many of those old
                    326:        problems back.</p>
                    327:
                    328:       <p>Currently we are even supporting the
                    329:        <code class="filename">/etc/ld.so.conf</code> functionality
                    330:        in our ELF linker, but it is not at all clear that a hybrid
                    331:        mechanism is the right solution. For that reason we do not
                    332:        advertise its existence, advocate its use, or even provide a
                    333:        default installation template. It is there for those who think
                    334:        that they really need it, and cannot live without it.</p>
                    335:
                    336:       <p>Here are some of the problems.
                    337:
                    338:        </p>
1.14      spz       339: <div class="orderedlist"><ol class="orderedlist" type="1">
                    340: <li class="listitem">It's a shotgun approach that incorrectly assumes all
1.1       dsieger   341:            images on the system will want to use the same search path.
                    342:            One advantage of the <span class="bold"><strong>-R</strong></span>
                    343:            mechanism is that different applications can use different
                    344:            library search paths.
                    345:            We could add exceptions to this, but it's more configuration
                    346:            steps...see below...</li>
1.14      spz       347: <li class="listitem">Another file in <code class="filename">/etc</code> is yet
1.1       dsieger   348:            another configuration knob to turn. This works against making
                    349:            the system easy to install and use.</li>
1.14      spz       350: <li class="listitem">The <code class="filename">/etc</code> file gets out of sync
1.1       dsieger   351:            with the installed system when configurations are changed or
                    352:            packages are added. The resulting failure mode can be confusing
                    353:            to some users.</li>
1.14      spz       354: <li class="listitem">The system should `just work'. We don't want to have
1.1       dsieger   355:            to indoctrinate users into editing the config file for
                    356:            packages, X11, <code class="filename">/usr/local</code>.</li>
1.14      spz       357: <li class="listitem">Would you think it is reasonable to provide a local
1.1       dsieger   358:            configuration search path for random data configuration
                    359:            files? Would a single path really apply for all applications?
                    360:            What if two applications had the same configuration file?
                    361:            What if two packages each want a
                    362:            "<code class="filename">libutil.so.1</code>"?</li>
                    363: </ol></div>
                    364: <p>
                    365:       </p>
                    366:
                    367:       <p>ELF tools are standardized packages maintained by third
                    368:        parties; these tools are used consistently on different operating
                    369:        systems and platforms. In the long run, the standardization
                    370:        provided by ELF will increase the quality of both systems and
                    371:        applications.</p>
                    372:
                    373:       <h4 class="title">
1.48      maya      374: <a name="elf-how-to-tell"></a>How do I tell if my system is ELF?</h4>
1.1       dsieger   375:
                    376:       <p>If you are running an ELF system your compiler will define
                    377:        the constant <span class="emphasis"><em>__ELF__</em></span>. You can use this in
                    378:        your C programs of course but you can also use the following
                    379:        shell script to determine it as well.</p>
                    380:
                    381:       <pre class="programlisting">if echo __ELF__ | ${CC:-cc} -E - | grep -q __ELF__
                    382: then echo "Not ELF"
                    383: else echo "It is an ELF system"
                    384: fi</pre>
1.3       dsieger   385:     <hr>Back to  <em><a href="./">NetBSD Documentation Top Level</a></em>
                    386: </div></div></div>
                    387: <div class="navfoot"></div>
1.12      mishka    388: <div id="footer"><div id="footerContent"><center>
1.38      maya      389: <span class="footfeed"><a href="//www.NetBSD.org/cgi-bin/feedback.cgi">
1.3       dsieger   390:          Contact</a> |
1.9       kano      391:       </span><span class="footcopy"><a href="../about/disclaimer.html">
1.3       dsieger   392:       Disclaimer</a> |
                    393:
1.54      maya      394:       <span class="copyright">Copyright © 1994-2019 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.<br>NetBSD<sup>®</sup> is a registered trademark of The NetBSD
1.3       dsieger   395:        Foundation, Inc.</span>
1.12      mishka    396: </center></div></div>
1.1       dsieger   397: </div></body>
                    398: </html>

CVSweb <webmaster@jp.NetBSD.org>