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

File: [cvs.NetBSD.org] / htdocs / docs / elf.xml (download)

Revision 1.3, Wed Sep 5 11:38:34 2018 UTC (3 years, 1 month ago) by maya
Branch: MAIN
CVS Tags: HEAD
Changes since 1.2: +2 -108 lines

Remove some legacy bits about how to update to ELF.

<?xml version="1.0"?>
<!DOCTYPE webpage
 PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
        "http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">

<webpage id="docs-elf">
<config param="desc" value="NetBSD ELF FAQ"/>
<config param="cvstag" value="$NetBSD: elf.xml,v 1.3 2018/09/05 11:38:34 maya Exp $"/>
<config param="rcsdate" value="$Date: 2018/09/05 11:38:34 $"/>
<head>

  <!-- Copyright (c) 1998-2003
       The NetBSD Foundation, Inc.  ALL RIGHTS RESERVED. -->
  <!--
    ==  By Ross Harvey
    -->

  <title>NetBSD ELF FAQ</title>
</head>

<sect1 role="toc">

  <sect2 id="elf-issues">
    <title>ELF Issues</title>

    <sect3 id="elf-whatis">
      <title>What is ELF?</title>

      <para>ELF is a binary format designed to support dynamic objects 
	and shared libraries. On older COFF and ECOFF systems, dynamic 
	support and shared libraries were not naturally supported by the 
	underlying format, leading to dynamic implementations that were 
	at times complex, quirky, and slow.</para>
    </sect3>

    <sect3 id="elf-dynamic-callbacks">
      <title>A dynamically loaded module at run-time couldn't find symbols 
	from my program image.</title>

      <para>You probably left off the 
	<emphasis role="bold">--export-dynamic</emphasis> option when
	linking the application. This is required only if arbitrary symbols 
	in the program might be needed by the dynamically loaded module, 
	for example, if a program intends to make run-time decisions to 
	dynamically load modules it was never linked with. Note, when
	running &man.cc.1; instead of &man.ld.1; this will be specified 
	as <emphasis role="bold">-Wl,--export-dynamic</emphasis>.</para>
    </sect3>

    <sect3 id="elf-ldconfig">
      <title>No need for ldconfig or for 
      	<filename>ld.so.conf</filename>!</title>

      <para>Ideally, there is no need for ldconfig or for  
      	<filename>/etc/ld.so.conf</filename>,
	since ELF provides good and predictable (read portable) mechanism
	to locate shared libraries. Unfortunately there are still a few
	corner cases (like wanting to run setuid binaries that you don't
	have the source for, that want shared libraries to be installed
	somewhere you don't like). For those corner cases, you'll find that
	creating an <filename>/etc/ld.so.conf</filename> file, will 
	still work. Read on though
	about other ways of doing this and why it is not a good idea. The
	next section discusses the ELF mechanisms for locating shared
	libraries.</para>
    </sect3>

    <sect3 id="elf-rpath">
      <title>My program can't find its shared library</title>

      <para>An ELF program needs to know the <emphasis>directory</emphasis> 
	and the <emphasis>filename</emphasis> required to &man.mmap.2; 
	its shared libraries. Encoded within the file name is version 
	information. There are one set of mechanisms for the directories 
	and a different mechanism for the file names.</para>
	
      <sect4 id="elf-rpath-dir">
	<title>Directories</title>

	<para>Although rarely used, the optional
	  <code>LD_LIBRARY_PATH</code> environment variable specifies
	  a colon-separated search path. This can be used in wrapper 
	  scripts as needed for misconfigured applications. It is 
	  <emphasis>ignored</emphasis> for setuid binaries.</para>
	
	<para>There is a built-in search path in the run-time loader:
	  <filename>ld.elf_so</filename>. On many systems this path 
	  consists only of <filename>/usr/lib</filename>; although on 
	  NetBSD versions prior to 1.4 it also searched
	  <filename>/usr/local/lib</filename>.</para>

	<para>The primary directory locating mechanism is the ``rpath'' 
	  search list contained within the executable image. This search 
	  list is set with the <emphasis role="bold">-R</emphasis>
	  directive to &man.ld.1;. The POSIX syntax for passing
	  &man.ld.1; options through the compiler front end is:</para>

	<para>&nbsp;&nbsp;&nbsp;&nbsp;<emphasis
	  role="bold">-Wl,</emphasis>
	  <emphasis>option,option,...</emphasis></para>
	  
	<para>For example: <code>-Wl,-R/usr/something/lib</code>.
	  Multiple <emphasis role="bold">-R</emphasis> directives can be 
	  given to a single application to create a shared library
	  search path.</para>

	<para>This directive is also known as 
	  <emphasis role="bold">-rpath</emphasis>. Using 
	  <emphasis role="bold">-R</emphasis> has the advantage of 
	  working in older versions of NetBSD as well.</para>
      </sect4>

      <sect4 id="elf-rpath-versions">
        <title>File Names and Versions</title>

	<para>When shared libraries are created, the <emphasis 
	  role="bold">-soname</emphasis> directive is used to record 
	  the major version number of the library in the internal 
	  <code>DT_SONAME</code> field. The actual library is installed 
	  as, for example,</para>

	  <itemizedlist>
	    <listitem><filename>libgizmo.so.4.2</filename> 
	      &nbsp;&nbsp;<emphasis>(the actual file)</emphasis></listitem>
	    <listitem><filename>libgizmo.so.4</filename>
	      &nbsp;&nbsp;<emphasis>(symbolic link)</emphasis></listitem>
	    <listitem><filename>libgizmo.so</filename>
	      &nbsp;&nbsp;<emphasis>(symbolic link)</emphasis></listitem>
	  </itemizedlist>

	<para>The idea is that Makefiles will want to link against only
	  the plain .so file. (Who would want to go around changing all 
	  the Makefiles just because a new library version was 
	  installed?) Once linked, however, the program 
	  <emphasis>does</emphasis> want to be aware of the major 
	  version but does <emphasis>not</emphasis> want to deal 
	  with the minor version.</para>

	<para>Consequently, the library itself knows that it is
	  <filename>libgizmo.so.4</filename> because a <emphasis 
	  role="bold">-soname <filename>libgizmo.so.4</filename></emphasis>
	  directive was used when it was created. The program knows 
	  it got major version 4 because the linker copied the
	  <filename>libgizmo.so.4</filename> <code>DT_SONAME</code> string 
	  out of the library and saved it in the executable.</para>

	<para>You don't say <emphasis 
	  role="bold">-soname <filename>libgizmo.so</filename></emphasis>, 
	  because then the program would use the latest major number 
	  and would break if that ever changed. (The major number only 
	  changes if the new library is incompatible.)
	  You don't say <emphasis 
	  role="bold">-soname <filename>libgizmo.so.4.2</filename></emphasis>,
	  because then the installation of a compatible change that 
	  bumps the minor number would unnecessarily break the linked 
	  images.</para>
      </sect4>
    </sect3>
      
    <sect3 id="elf-examples">
      <title>Elf Shared Library Examples</title>

      <para>To compile <filename>f.c</filename> and make an installable 
      	shared library out of it:</para>

	<programlisting>cc -O  -Werror  -c -fpic -DPIC f.c -o f.so
ar cq libf_pic.a `NM=nm lorder f.so | tsort -q`
ld -x -shared -R/my/directory/lib -soname libf.so.4 -o \
&nbsp;&nbsp;&nbsp;libf.so.4.9  /usr/lib/crtbeginS.o  --whole-archive \
&nbsp;&nbsp;&nbsp;libf_pic.a /usr/lib/crtendS.o</programlisting>

      <para>There is another way:</para>
      
      <programlisting>% cat Makefile
LIB=f
SRCS=f.c
.include &lt;bsd.lib.mk&gt;
% cat shlib_version
major=4
minor=9
% make

You can disable some of the <code>Makefile</code> targets with NOPROFILE=1 and NOSTATICLIB=1.</programlisting>

      <para>And there is <emphasis>another</emphasis> way:</para>

      <blockquote><code>libtool</code> -
	The <code>libtool</code> package is a large shell script used to
	manage shared and static libraries in a platform-independent fashion.
	There is a NetBSD <filename role="pkg">devel/libtool</filename> package
	and even a <ulink 
	url="http://www.gnu.org/software/libtool/libtool.html">
	<code>libtool</code> home page</ulink>.
      </blockquote>
    </sect3>

    <sect3 id="elf-ldconfig-revisited">
      <title>But I Want ldconfig! &nbsp;&nbsp;&nbsp;I Want ld.so.conf!  I want it! I want it! I want it!</title>

      <para>At first glance, it might seem reasonable, why shouldn't 
	people be able to move things around to anywhere they want and
	correct the consequent lossage in a 
	<filename>/etc</filename> file?</para>
      
      <para>In fact, some developers of ELF systems have apparently
	added such a file, but with mixed results. The ELF mechanism 
	was designed to correct some of the previous problems, and 
	introducing the old mechanism would bring many of those old 
	problems back.</para>

      <para>Currently we are even supporting the
	<filename>/etc/ld.so.conf</filename> functionality
	in our ELF linker, but it is not at all clear that a hybrid 
	mechanism is the right solution. For that reason we do not 
	advertise its existence, advocate its use, or even provide a 
	default installation template. It is there for those who think 
	that they really need it, and cannot live without it.</para>

      <para>Here are some of the problems.
	
	<orderedlist>
	  <listitem>It's a shotgun approach that incorrectly assumes all
	    images on the system will want to use the same search path.
	    One advantage of the <emphasis role="bold">-R</emphasis>
	    mechanism is that different applications can use different
	    library search paths.
	    We could add exceptions to this, but it's more configuration
	    steps...see below...</listitem>
	  <listitem>Another file in <filename>/etc</filename> is yet 
	    another configuration knob to turn. This works against making 
	    the system easy to install and use.</listitem>
	  <listitem>The <filename>/etc</filename> file gets out of sync 
	    with the installed system when configurations are changed or 
	    packages are added. The resulting failure mode can be confusing 
	    to some users.</listitem>
	  <listitem>The system should `just work'. We don't want to have 
	    to indoctrinate users into editing the config file for
	    packages, X11, <filename>/usr/local</filename>.</listitem>
	  <listitem>Would you think it is reasonable to provide a local
	    configuration search path for random data configuration
	    files? Would a single path really apply for all applications?
	    What if two applications had the same configuration file?
	    What if two packages each want a
	    "<filename>libutil.so.1</filename>"?</listitem>
	</orderedlist>
      </para>

      <para>ELF tools are standardized packages maintained by third
	parties; these tools are used consistently on different operating 
	systems and platforms. In the long run, the standardization 
	provided by ELF will increase the quality of both systems and 
	applications.</para>
    </sect3>

    <sect3 id="elf-how-to-tell">
      <title>How do I tell if my system is ELF?</title>
	
      <para>If you are running an ELF system your compiler will define 
	the constant <emphasis>__ELF__</emphasis>. You can use this in 
	your C programs of course but you can also use the following 
	shell script to determine it as well.</para>
	
      <programlisting>if echo __ELF__ | ${CC:-cc} -E - | grep -q __ELF__
then echo "Not ELF"
else echo "It is an ELF system"
fi</programlisting>
    </sect3>
  </sect2>
</sect1>
<parentsec url="./" text="NetBSD Documentation Top Level"/>
</webpage>