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: “Of course it runs NetBSD”
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 & 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 & 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> <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: <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: <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: <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: libf.so.4.9 /usr/lib/crtbeginS.o --whole-archive \
288: 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 <bsd.lib.mk>
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! 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>