README

   1 This is the public release of libelf-0.8.13, a free ELF object
   2 file access library. If you have problems with applications
   3 that use libelf and work with the commercial (SVR4, Solaris)
   4 version but not with this one, please contact me.
   5
   6 IMPORTANT NOTE: If you have libelf-0.5.2 installed, you probably
   7 have a file .../include/elf.h that contains the single line
   8 ``#include <libelf/elf.h>''. REMOVE THIS FILE BEFORE YOU RUN
   9 configure.
  10
  11 Installation is straightforward - the package is autoconf'ed.  Just do
  12 ``cd libelf-0.8.13; ./configure; make; make install''.  Header files
  13 will be installed in .../include/libelf/.  If your system does not
  14 provide its own versions of libelf.h, nlist.h or gelf.h, ``make
  15 install'' will add the missing headers.  If you prefer not to have
  16 these files installed in /usr/include, use ``--disable-compat'' and
  17 add ``-I /usr/include/libelf'' to your CFLAGS when compiling
  18 libelf-based programs.
  19
  20 Note to distribution makers:  You can install libelf in a separate root
  21 hierarchy by using the command ``make instroot=/my/root install''.
  22 You should also use the ``--enable-compat'' configure option in that
  23 case, or run ``make instroot=/my/root install-compat'' manually, to
  24 install all the required header files.
  25
  26 If you are running Linux with libc 5.* as the default C library,
  27 and you plan to use the 64-bit functions, you must either use
  28 ``-I.../include/libelf'', or remove /usr/include/libelf.h and use
  29 ``--enable-compat'' when running configure. Libc 6.* (aka glibc2)
  30 doesn't have its own <libelf.h>, <nlist.h> or <gelf.h>.
  31
  32 You need an ANSI/ISO C compiler to build libelf. Gcc is optimal.
  33
  34 On some systems (in particular, Solaris and all variants of Linux),
  35 ``make'' will try to build a shared library. If you run into problems
  36 on your system, please pass ``--disable-shared'' to configure.
  37 If you build a shared library and want it to be installed as
  38 ``libelf-0.8.13.so'' rather than ``libelf.so.0.8.13'', please use
  39 ``./configure --enable-gnu-names''. Other files, e.g. ``libelf.so'' and
  40 ``libelf.so.0'' are NOT affected.
  41
  42 Another configure option, ``--enable-debug'', adds debugging code to
  43 libelf; if you don't run into problems, you will probably not need it.
  44
  45 When creating an ELF shared library, it is possible to add references
  46 to other shared libraries in the DYNAMIC section of the resulting
  47 file. The make variable DEPSHLIBS contains a list of libraries to add.
  48 It is set to ``-lc'' on Linux systems, and empty otherwise. To
  49 override this setting, use something like ``make DEPSHLIBS="-la -lb"''.
  50 For Linux, `-lc' is included automagically.
  51
  52 NLS is available and enabled by default.  To turn it off, pass the
  53 ``--disable-nls'' option to configure.
  54
  55 Libelf can use gettext or catgets for accessing message
  56 catalogs.  If gettext is available AND is part of libc (i.e. not
  57 in a separate library), it will be used. Otherwise, configure
  58 will look for catgets.  If you have gettext in a separate
  59 library and want to use it, you should pass the library's name
  60 to configure, e.g. ``LIBS=-lintl ./configure''. Note that you
  61 MUST link your libelf-based applications with -lintl then,
  62 which is probably not what you want, or change the DEPSHLIBS variable
  63 described above (in case you're building a shared library).
  64
  65 If you have GNU gettext 0.10 installed on your system, and if GNU gettext
  66 runs on top of the catgets interface (rather old Linux systems, using
  67 libc5), configure will refuse to use it and use catgets instead. If you
  68 absolutely want to use GNU gettext, go ahead and rebuild it (which is
  69 IMHO a good idea in general in this case):
  70
  71         cd .../gettext-0.10
  72         ac_cv_func_catgets=no ac_cv_func_gettext=no ./configure
  73         make
  74         make install
  75
  76 After that, return to the libelf build directory, remove
  77 config.cache, and start over.
  78
  79 *** Large File Support (LFS) applications ***
  80
  81 Some 32-bit systems support files that are larger than the address space
  82 of the architecture.  On these, the `off_t' data type may have 32 or
  83 64 bits, depending on the API you choose.  Since off_t is also part of
  84 the libelf API, in particular the Elf_Data and Elf_Arhdr structures,
  85 an application compiled with large file support will need a version of
  86 libelf that has also been compiled with LFS; otherwise, it won't work
  87 correctly.  Similarly, a program compiled without LFS needs a library
  88 compiled without LFS.
  89
  90 Note that libelf is currently unable to process large files on 32-bit
  91 architectures, whether you compile it for LFS or not, for the simple
  92 reason that the files won't fit into the processes' address space.
  93 Therefore, libelf is compiled without LFS by default.  It can of course
  94 read and write ELF files for 64-bit architectures, but they will be
  95 limited in length on a 32-bit system.
  96
  97 You may compile libelf with large file support by setting CPPFLAGS at
  98 configuration time:
  99
 100         CPPFLAGS=`getconf LFS_CFLAGS` ./configure
 101
 102 But I really, really recommend you don't, because it breaks binary
 103 compatibility with existing libelf based applications.
 104
 105 *** 64-bit support ***
 106
 107 Starting with libelf-0.7.0, libelf also supports 64-bit ELF files.
 108 This is enabled by default unless your system (or your compiler) does
 109 not support 64-bit integers, or lacks 64-bit declarations in <elf.h>.
 110 If you have problems building with 64-bit support, please do
 111
 112     ./configure --disable-elf64
 113
 114 for the moment, and contact me. Please note that I haven't tested 64-bit
 115 support much.  There are still some unresolved problems, e.g. IRIX
 116 uses different Elf64_Rel and Elf64_Rela structures (they replaced the
 117 r_info member), and the enumeration values for Elf_Type differ from
 118 the commercial (SVR4) implementation of libelf - they broke binary
 119 compatibility for no good reason, and I'm not willing to follow their
 120 footsteps. The result is that libelf-0.7.* ist upward compatible with
 121 libelf-0.6.4 (as it should be) but INCOMPATIBLE WITH SVR4 LIBELF. If you
 122 have both versions installed, you'd better make sure that you link with
 123 the library that matches the <libelf.h> you're #include'ing.
 124
 125 *** Symbol Versioning ***
 126
 127 Libelf >= 0.8.0 supports the data structures and definitions used for
 128 symbol versioning on Solaris and Linux, in particular, the Elfxx_Verdef,
 129 Elfxx_Verdaux, Elfxx_Verneed, Elfxx_Vernaux and Elfxx_Versym structures
 130 and the SHT_XXX_verdef, SHT_XXX_verneed and SHT_XXX_versym section types
 131 (where `xx' is either `32' or `64', and `XXX' is either `SUNW' or `GNU').
 132 Libelf now translates versioning sections to/from their external
 133 representation properly (earlier versions left them in `raw' format,
 134 with the data type set to ELF_T_BYTE).  This may cause problems on
 135 systems which use the same (OS-specific) section types for different
 136 purposes.  The configure program tries to figure out if your OS uses
 137 versioning; if that check fails, you can use
 138
 139     ./configure --disable-versioning
 140
 141 to turn off versioning translation support.
 142
 143 *** W32 Support ***
 144
 145 There is now some support for building on W32 systems (requires Microsoft
 146 VC++).  In order to build a W32 DLL, cd into the `lib' subdirectory, edit
 147 build.bat if necessary (it needs the path to your compiler binaries) and
 148 run it.  If you're lucky, libelf.dll and the import/export libraries will
 149 be built.  If not, please drop me a line.
 150
 151 I tested it on XP Pro (SP2), using VC++ 2005 Express Edition.
 152 Apparently, Visual Studio .NET 2003 works fine as well.
 153
 154 Various notes regarding the W32 port:
 155
 156     - When you open() an ELF file, remember to use the O_BINARY flag.
 157     - You may have to add /MD to the linker command line.
 158
 159 *** Missing things ***
 160
 161         * There is no documentation.  You can use the Solaris
 162           manpages instead (available at http://docs.sun.com/).
 163           The ELF file format is described in several places;
 164           among them Suns "Linker and Libraries Guide" and the
 165           "System V Application Binary Interface" documents;
 166           http://www.caldera.com/developer/devspecs/gabi41.pdf and
 167           http://www.caldera.com/developer/gabi/ are probably good
 168           starting points. Processor-specific documentation is spread
 169           across a number of `Processor Supplement' documents, one
 170           for each architecture; you'll have to use a search engine to
 171           find them.
 172
 173         * The COFF file format is not understood. This is so obsolete
 174           that it will probably never be implemented.
 175
 176         * nlist(3) is incomplete; the n_type and n_sclass
 177           members of struct nl are set to zero even if type
 178           (that is, debug) information is available.
 179
 180         * Libelf does not translate Solaris' `Move' and `Syminfo'
 181           sections. You can read them using elf_getdata(), but you'll
 182           only get raw (untranslated) bytes.
 183
 184 Changes since 0.8.12:
 185
 186         * New function elf_getaroff().
 187
 188         * Build fixes.
 189
 190 Changes since 0.8.11:
 191
 192         * Due to some unfortunate confusion, the elf_getphnum(),
 193           elf_getshnum() and elf_getshstrndx() are not compatible
 194           between libelf implementations. Therefore, the developers
 195           decided to replace them with new functions: elf_getphdrnum(),
 196           elf_getshdrnum() and elf_getshdrstrndx(), which will always
 197           return -1 on failure and 0 on success. Code using the old
 198           interface should be upgraded to increase portability.
 199
 200 Changes since 0.8.10:
 201
 202         * Fixed a bug in elf_rawfile().
 203         * If you use ELF_F_LAYOUT together with ELF_F_LAYOUT_OVERLAP,
 204           elf_update() will now tolerate overlapping sections.
 205
 206 Changes since 0.8.9:
 207
 208         * Ported to QNX Neutrino.
 209         * Fixed Windows build errors.
 210         * Parallel (make -j) installation should work now.
 211
 212         * It's now possible to enable and disable select sanity checks
 213           libelf performs. Currently, this affects the "NUL terminated
 214           string table entry" check performed in elf_strptr(). By
 215           default, the function will return an error if the string
 216           requested is not properly terminated - because some
 217           applications might dump core otherwise. If you configure
 218           libelf with `--disable-sanity-checks', however, the check
 219           (and, in the future, probably others as well) is disabled
 220           by default. You can still turn it on and off at runtime by
 221           setting the LIBELF_SANITY_CHECKS environment variable to
 222           an integer value:
 223
 224               # disable all sanity checks
 225               export LIBELF_SANITY_CHECKS=0
 226
 227               # enable all sanity checks
 228               export LIBELF_SANITY_CHECKS=-1
 229
 230           Each bit of the value corresponds to a particular check,
 231           so you could use LIBELF_SANITY_CHECKS=1 to enable only
 232           the elf_strptr() check. You may also use a value in hex
 233           (0x...) or octal (0...) format.
 234
 235 Changes since 0.8.8:
 236
 237         * Improved translator for symbol versioning sections.
 238         * The W32 library is now built in the `lib' subdirectory.
 239         * Windows DLLs should work now.
 240
 241 Changes since 0.8.6:
 242
 243         * added elf_getphnum().
 244         * added elf_getshnum().
 245         * added elf_getshstrndx().
 246         * added elfx_update_shstrndx().
 247         * handle interrupted reads/writes more gracefully.
 248         * added (partial) support for unusual e_[ps]hentsize values.
 249         * fixed the bugs introduced in 0.8.7.
 250
 251 Changes since 0.8.5:
 252
 253         * added W32 support.
 254         * added workaround for alignment errors in archive members.
 255         * my email address has changed again ;)
 256
 257 Changes since 0.8.4:
 258
 259         * elf_strptr() should now work more safely with fragmented
 260           or badly formatted string tables.
 261
 262 Changes since 0.8.3:
 263
 264         * Fixed a bug in elf_update() that was introduced in 0.8.3.
 265
 266 Changes since 0.8.2:
 267
 268         * Should compile on MacOSX now.
 269
 270         * Can read and write files with more than 65280 sections
 271
 272         * Tries to handle 64-bit ELF files that use 8-byte hash table
 273           entries. In particular, libelf tries to guess the data type in
 274           elf_getdata(), and doesn't override sh_entsize in elf_update()
 275           any longer. If you want the library to pick the entry size,
 276           you must set its value to 0 before you call elf_update().
 277
 278         * No longer dumps core in elf_update() when a versioning section
 279           has no data. Instead, it returns an error message. Note that
 280           you're supposed to provide a valid d_buf for any section, unless
 281           it's empty or has SHT_NOBITS type.
 282
 283         * Building a shared library is now the default (if supported).
 284
 285 Changes since 0.8.0:
 286
 287         * Corrected typo in lib/{32,64}.xlatetof.c that sometimes
 288           caused a compilation failure.
 289
 290         * Use open(name, O_RDONLY|O_BINARY) in lib/nlist.c.
 291
 292 Changes since 0.7.0:
 293
 294         * I implemented the gelf_* interface, as found on Solaris.
 295           I don't know whether it's compatible -- the Solaris manpage
 296           isn't very specific, so I had to guess return values etc. in
 297           some cases.
 298
 299         * Added elf{32,64}_checksum (supposed to be compatible with
 300           Solaris).
 301
 302         * Added symbol versioning support.
 303
 304 Changes since 0.6.4:
 305
 306         * Fixed configure for IRIX systems
 307         * Added check for truncated archive members
 308         * Added check for misaligned SHDR/PHDR tables
 309         * Support for building libelf together with GNU libc
 310         * Added elf_memory(3)
 311         * Added 64-bit support
 312
 313 Changes since 0.5.2:
 314
 315         * some bug fixes
 316         * mmap support
 317         * new directory layout
 318         * There is a new function, elf_delscn(), that deletes
 319           a section from an ELF file. It also adjusts the
 320           sh_link and sh_info members in the section header
 321           table, if (and ONLY if) the ELF standard indicates
 322           that these values are section indices. References
 323           to the deleted section will be cleared, so be careful.
 324         * my email address has changed ;)
 325
 326 Where to get libelf:
 327
 328         ftp://ftp.ibiblio.org/pub/Linux/libs/
 329         http://www.mr511.de/software/
 330
 331 Michael "Tired" Riepe
 332 <libelf@mr511.de>