|
1 This is the public release of libelf-0.8.10, 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.10; ./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.10.so'' rather than ``libelf.so.0.8.10'', 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.9: |
|
185 |
|
186 * Ported to QNX Neutrino. |
|
187 * Fixed Windows build errors. |
|
188 * Parallel (make -j) installation should work now. |
|
189 |
|
190 * It's now possible to enable and disable select sanity checks |
|
191 libelf performs. Currently, this affects the "NUL terminated |
|
192 string table entry" check performed in elf_strptr(). By |
|
193 default, the function will return an error if the string |
|
194 requested is not properly terminated - because some |
|
195 applications might dump core otherwise. If you configure |
|
196 libelf with `--disable-sanity-checks', however, the check |
|
197 (and, in the future, probably others as well) is disabled |
|
198 by default. You can still turn it on and off at runtime by |
|
199 setting the LIBELF_SANITY_CHECKS environment variable to |
|
200 an integer value: |
|
201 |
|
202 # disable all sanity checks |
|
203 export LIBELF_SANITY_CHECKS=0 |
|
204 |
|
205 # enable all sanity checks |
|
206 export LIBELF_SANITY_CHECKS=-1 |
|
207 |
|
208 Each bit of the value corresponds to a particular check, |
|
209 so you could use LIBELF_SANITY_CHECKS=1 to enable only |
|
210 the elf_strptr() check. You may also use a value in hex |
|
211 (0x...) or octal (0...) format. |
|
212 |
|
213 Changes since 0.8.8: |
|
214 |
|
215 * Improved translator for symbol versioning sections. |
|
216 * The W32 library is now built in the `lib' subdirectory. |
|
217 * Windows DLLs should work now. |
|
218 |
|
219 Changes since 0.8.6: |
|
220 |
|
221 * added elf_getphnum(). |
|
222 * added elf_getshnum(). |
|
223 * added elf_getshstrndx(). |
|
224 * added elfx_update_shstrndx(). |
|
225 * handle interrupted reads/writes more gracefully. |
|
226 * added (partial) support for unusual e_[ps]hentsize values. |
|
227 * fixed the bugs introduced in 0.8.7. |
|
228 |
|
229 Changes since 0.8.5: |
|
230 |
|
231 * added W32 support. |
|
232 * added workaround for alignment errors in archive members. |
|
233 * my email address has changed again ;) |
|
234 |
|
235 Changes since 0.8.4: |
|
236 |
|
237 * elf_strptr() should now work more safely with fragmented |
|
238 or badly formatted string tables. |
|
239 |
|
240 Changes since 0.8.3: |
|
241 |
|
242 * Fixed a bug in elf_update() that was introduced in 0.8.3. |
|
243 |
|
244 Changes since 0.8.2: |
|
245 |
|
246 * Should compile on MacOSX now. |
|
247 |
|
248 * Can read and write files with more than 65280 sections |
|
249 |
|
250 * Tries to handle 64-bit ELF files that use 8-byte hash table |
|
251 entries. In particular, libelf tries to guess the data type in |
|
252 elf_getdata(), and doesn't override sh_entsize in elf_update() |
|
253 any longer. If you want the library to pick the entry size, |
|
254 you must set its value to 0 before you call elf_update(). |
|
255 |
|
256 * No longer dumps core in elf_update() when a versioning section |
|
257 has no data. Instead, it returns an error message. Note that |
|
258 you're supposed to provide a valid d_buf for any section, unless |
|
259 it's empty or has SHT_NOBITS type. |
|
260 |
|
261 * Building a shared library is now the default (if supported). |
|
262 |
|
263 Changes since 0.8.0: |
|
264 |
|
265 * Corrected typo in lib/{32,64}.xlatetof.c that sometimes |
|
266 caused a compilation failure. |
|
267 |
|
268 * Use open(name, O_RDONLY|O_BINARY) in lib/nlist.c. |
|
269 |
|
270 Changes since 0.7.0: |
|
271 |
|
272 * I implemented the gelf_* interface, as found on Solaris. |
|
273 I don't know whether it's compatible -- the Solaris manpage |
|
274 isn't very specific, so I had to guess return values etc. in |
|
275 some cases. |
|
276 |
|
277 * Added elf{32,64}_checksum (supposed to be compatible with |
|
278 Solaris). |
|
279 |
|
280 * Added symbol versioning support. |
|
281 |
|
282 Changes since 0.6.4: |
|
283 |
|
284 * Fixed configure for IRIX systems |
|
285 * Added check for truncated archive members |
|
286 * Added check for misaligned SHDR/PHDR tables |
|
287 * Support for building libelf together with GNU libc |
|
288 * Added elf_memory(3) |
|
289 * Added 64-bit support |
|
290 |
|
291 Changes since 0.5.2: |
|
292 |
|
293 * some bug fixes |
|
294 * mmap support |
|
295 * new directory layout |
|
296 * There is a new function, elf_delscn(), that deletes |
|
297 a section from an ELF file. It also adjusts the |
|
298 sh_link and sh_info members in the section header |
|
299 table, if (and ONLY if) the ELF standard indicates |
|
300 that these values are section indices. References |
|
301 to the deleted section will be cleared, so be careful. |
|
302 * my email address has changed ;) |
|
303 |
|
304 Where to get libelf: |
|
305 |
|
306 ftp://ftp.ibiblio.org/pub/Linux/libs/ |
|
307 http://www.mr511.de/software/ |
|
308 |
|
309 Michael "Tired" Riepe |
|
310 <libelf@mr511.de> |