diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 332 |
1 files changed, 332 insertions, 0 deletions
@@ -0,0 +1,332 @@ +This is the public release of libelf-0.8.13, 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.13; ./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.13.so'' rather than ``libelf.so.0.8.13'', 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.12: + + * New function elf_getaroff(). + + * Build fixes. + +Changes since 0.8.11: + + * Due to some unfortunate confusion, the elf_getphnum(), + elf_getshnum() and elf_getshstrndx() are not compatible + between libelf implementations. Therefore, the developers + decided to replace them with new functions: elf_getphdrnum(), + elf_getshdrnum() and elf_getshdrstrndx(), which will always + return -1 on failure and 0 on success. Code using the old + interface should be upgraded to increase portability. + +Changes since 0.8.10: + + * Fixed a bug in elf_rawfile(). + * If you use ELF_F_LAYOUT together with ELF_F_LAYOUT_OVERLAP, + elf_update() will now tolerate overlapping sections. + +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> |