README
332 lines
| 12.9 KiB
| text/plain
|
TextLexer
Jeandet Alexis
|
r0 | 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> | ||||