This is the public release of libelf-0.8.10, a free ELF object

file access library. If you have problems with applications

that use libelf and work with the commercial (SVR4, Solaris)

version but not with this one, please contact me.

IMPORTANT NOTE: If you have libelf-0.5.2 installed, you probably

have a file .../include/elf.h that contains the single line

``#include <libelf/elf.h>''. REMOVE THIS FILE BEFORE YOU RUN

configure.

Installation is straightforward - the package is autoconf'ed.  Just do

``cd libelf-0.8.10; ./configure; make; make install''.  Header files

will be installed in .../include/libelf/.  If your system does not

provide its own versions of libelf.h, nlist.h or gelf.h, ``make

install'' will add the missing headers.  If you prefer not to have

these files installed in /usr/include, use ``--disable-compat'' and

add ``-I /usr/include/libelf'' to your CFLAGS when compiling

libelf-based programs.

Note to distribution makers:  You can install libelf in a separate root

hierarchy by using the command ``make instroot=/my/root install''.

You should also use the ``--enable-compat'' configure option in that

case, or run ``make instroot=/my/root install-compat'' manually, to

install all the required header files.

If you are running Linux with libc 5.* as the default C library,

and you plan to use the 64-bit functions, you must either use

``-I.../include/libelf'', or remove /usr/include/libelf.h and use

``--enable-compat'' when running configure. Libc 6.* (aka glibc2)

doesn't have its own <libelf.h>, <nlist.h> or <gelf.h>.

You need an ANSI/ISO C compiler to build libelf. Gcc is optimal.

On some systems (in particular, Solaris and all variants of Linux),

``make'' will try to build a shared library. If you run into problems

on your system, please pass ``--disable-shared'' to configure.

If you build a shared library and want it to be installed as

``libelf-0.8.10.so'' rather than ``libelf.so.0.8.10'', please use

``./configure --enable-gnu-names''. Other files, e.g. ``libelf.so'' and

``libelf.so.0'' are NOT affected.

Another configure option, ``--enable-debug'', adds debugging code to

libelf; if you don't run into problems, you will probably not need it.

When creating an ELF shared library, it is possible to add references

to other shared libraries in the DYNAMIC section of the resulting

file. The make variable DEPSHLIBS contains a list of libraries to add.

It is set to ``-lc'' on Linux systems, and empty otherwise. To

override this setting, use something like ``make DEPSHLIBS="-la -lb"''.

For Linux, `-lc' is included automagically.

NLS is available and enabled by default.  To turn it off, pass the

``--disable-nls'' option to configure.

Libelf can use gettext or catgets for accessing message

catalogs.  If gettext is available AND is part of libc (i.e. not

in a separate library), it will be used. Otherwise, configure

will look for catgets.  If you have gettext in a separate

library and want to use it, you should pass the library's name

to configure, e.g. ``LIBS=-lintl ./configure''. Note that you

MUST link your libelf-based applications with -lintl then,

which is probably not what you want, or change the DEPSHLIBS variable

described above (in case you're building a shared library).

If you have GNU gettext 0.10 installed on your system, and if GNU gettext

runs on top of the catgets interface (rather old Linux systems, using

libc5), configure will refuse to use it and use catgets instead. If you

absolutely want to use GNU gettext, go ahead and rebuild it (which is

IMHO a good idea in general in this case):

	cd .../gettext-0.10

	ac_cv_func_catgets=no ac_cv_func_gettext=no ./configure

	make

	make install

After that, return to the libelf build directory, remove

config.cache, and start over.

*** Large File Support (LFS) applications ***

Some 32-bit systems support files that are larger than the address space

of the architecture.  On these, the `off_t' data type may have 32 or

64 bits, depending on the API you choose.  Since off_t is also part of

the libelf API, in particular the Elf_Data and Elf_Arhdr structures,

an application compiled with large file support will need a version of

libelf that has also been compiled with LFS; otherwise, it won't work

correctly.  Similarly, a program compiled without LFS needs a library

compiled without LFS.

Note that libelf is currently unable to process large files on 32-bit

architectures, whether you compile it for LFS or not, for the simple

reason that the files won't fit into the processes' address space.

Therefore, libelf is compiled without LFS by default.  It can of course

read and write ELF files for 64-bit architectures, but they will be

limited in length on a 32-bit system.

You may compile libelf with large file support by setting CPPFLAGS at

configuration time:

	CPPFLAGS=`getconf LFS_CFLAGS` ./configure

But I really, really recommend you don't, because it breaks binary

compatibility with existing libelf based applications.

*** 64-bit support ***

Starting with libelf-0.7.0, libelf also supports 64-bit ELF files.

This is enabled by default unless your system (or your compiler) does

not support 64-bit integers, or lacks 64-bit declarations in <elf.h>.

If you have problems building with 64-bit support, please do

    ./configure --disable-elf64

for the moment, and contact me. Please note that I haven't tested 64-bit

support much.  There are still some unresolved problems, e.g. IRIX

uses different Elf64_Rel and Elf64_Rela structures (they replaced the

r_info member), and the enumeration values for Elf_Type differ from

the commercial (SVR4) implementation of libelf - they broke binary

compatibility for no good reason, and I'm not willing to follow their

footsteps. The result is that libelf-0.7.* ist upward compatible with

libelf-0.6.4 (as it should be) but INCOMPATIBLE WITH SVR4 LIBELF. If you

have both versions installed, you'd better make sure that you link with

the library that matches the <libelf.h> you're #include'ing.

*** Symbol Versioning ***

Libelf >= 0.8.0 supports the data structures and definitions used for

symbol versioning on Solaris and Linux, in particular, the Elfxx_Verdef,

Elfxx_Verdaux, Elfxx_Verneed, Elfxx_Vernaux and Elfxx_Versym structures

and the SHT_XXX_verdef, SHT_XXX_verneed and SHT_XXX_versym section types

(where `xx' is either `32' or `64', and `XXX' is either `SUNW' or `GNU').

Libelf now translates versioning sections to/from their external

representation properly (earlier versions left them in `raw' format,

with the data type set to ELF_T_BYTE).  This may cause problems on

systems which use the same (OS-specific) section types for different

purposes.  The configure program tries to figure out if your OS uses

versioning; if that check fails, you can use

    ./configure --disable-versioning

to turn off versioning translation support.

*** W32 Support ***

There is now some support for building on W32 systems (requires Microsoft

VC++).  In order to build a W32 DLL, cd into the `lib' subdirectory, edit

build.bat if necessary (it needs the path to your compiler binaries) and

run it.  If you're lucky, libelf.dll and the import/export libraries will

be built.  If not, please drop me a line.

I tested it on XP Pro (SP2), using VC++ 2005 Express Edition.

Apparently, Visual Studio .NET 2003 works fine as well.

Various notes regarding the W32 port:

    - When you open() an ELF file, remember to use the O_BINARY flag.

    - You may have to add /MD to the linker command line.

*** Missing things ***

	* There is no documentation.  You can use the Solaris

	  manpages instead (available at http://docs.sun.com/).

	  The ELF file format is described in several places;

	  among them Suns "Linker and Libraries Guide" and the

	  "System V Application Binary Interface" documents;

	  http://www.caldera.com/developer/devspecs/gabi41.pdf and

	  http://www.caldera.com/developer/gabi/ are probably good

	  starting points. Processor-specific documentation is spread

	  across a number of `Processor Supplement' documents, one

	  for each architecture; you'll have to use a search engine to

	  find them.

	* The COFF file format is not understood. This is so obsolete

	  that it will probably never be implemented.

	* nlist(3) is incomplete; the n_type and n_sclass

	  members of struct nl are set to zero even if type

	  (that is, debug) information is available.

	* Libelf does not translate Solaris' `Move' and `Syminfo'

	  sections. You can read them using elf_getdata(), but you'll

	  only get raw (untranslated) bytes.

Changes since 0.8.9:

	* Ported to QNX Neutrino.

	* Fixed Windows build errors.

	* Parallel (make -j) installation should work now.

	* It's now possible to enable and disable select sanity checks

	  libelf performs. Currently, this affects the "NUL terminated

	  string table entry" check performed in elf_strptr(). By

	  default, the function will return an error if the string

	  requested is not properly terminated - because some

	  applications might dump core otherwise. If you configure

	  libelf with `--disable-sanity-checks', however, the check

	  (and, in the future, probably others as well) is disabled

	  by default. You can still turn it on and off at runtime by

	  setting the LIBELF_SANITY_CHECKS environment variable to

	  an integer value:

	      # disable all sanity checks

	      export LIBELF_SANITY_CHECKS=0

	      # enable all sanity checks

	      export LIBELF_SANITY_CHECKS=-1

	  Each bit of the value corresponds to a particular check,

	  so you could use LIBELF_SANITY_CHECKS=1 to enable only

	  the elf_strptr() check. You may also use a value in hex

	  (0x...) or octal (0...) format.

Changes since 0.8.8:

	* Improved translator for symbol versioning sections.

	* The W32 library is now built in the `lib' subdirectory.

	* Windows DLLs should work now.

Changes since 0.8.6:

	* added elf_getphnum().

	* added elf_getshnum().

	* added elf_getshstrndx().

	* added elfx_update_shstrndx().

	* handle interrupted reads/writes more gracefully.

	* added (partial) support for unusual e_[ps]hentsize values.

	* fixed the bugs introduced in 0.8.7.

Changes since 0.8.5:

	* added W32 support.

	* added workaround for alignment errors in archive members.

	* my email address has changed again ;)

Changes since 0.8.4:

	* elf_strptr() should now work more safely with fragmented

	  or badly formatted string tables.

Changes since 0.8.3:

	* Fixed a bug in elf_update() that was introduced in 0.8.3.

Changes since 0.8.2:

	* Should compile on MacOSX now.

	* Can read and write files with more than 65280 sections

	* Tries to handle 64-bit ELF files that use 8-byte hash table

	  entries. In particular, libelf tries to guess the data type in

	  elf_getdata(), and doesn't override sh_entsize in elf_update()

	  any longer. If you want the library to pick the entry size,

	  you must set its value to 0 before you call elf_update().

	* No longer dumps core in elf_update() when a versioning section

	  has no data. Instead, it returns an error message. Note that

	  you're supposed to provide a valid d_buf for any section, unless

	  it's empty or has SHT_NOBITS type.

	* Building a shared library is now the default (if supported).

Changes since 0.8.0:

	* Corrected typo in lib/{32,64}.xlatetof.c that sometimes

	  caused a compilation failure.

	* Use open(name, O_RDONLY|O_BINARY) in lib/nlist.c.

Changes since 0.7.0:

	* I implemented the gelf_* interface, as found on Solaris.

	  I don't know whether it's compatible -- the Solaris manpage

	  isn't very specific, so I had to guess return values etc. in

	  some cases.

	* Added elf{32,64}_checksum (supposed to be compatible with

	  Solaris).

	* Added symbol versioning support.

Changes since 0.6.4:

	* Fixed configure for IRIX systems

	* Added check for truncated archive members

	* Added check for misaligned SHDR/PHDR tables

	* Support for building libelf together with GNU libc

	* Added elf_memory(3)

	* Added 64-bit support

Changes since 0.5.2:

	* some bug fixes

	* mmap support

	* new directory layout

	* There is a new function, elf_delscn(), that deletes

	  a section from an ELF file. It also adjusts the

	  sh_link and sh_info members in the section header

	  table, if (and ONLY if) the ELF standard indicates

	  that these values are section indices. References

	  to the deleted section will be cleared, so be careful.

	* my email address has changed ;)

Where to get libelf:

	ftp://ftp.ibiblio.org/pub/Linux/libs/

	http://www.mr511.de/software/

Michael "Tired" Riepe

<libelf@mr511.de>