
					ELFSH README
					~~~~~~~~~~~~

Hello programmers from the world,

Try to read this README, its a precious information ressource for the ELF shell project . 

For impatient people, this is a short list for libelfsh's already provided features : Mass file
view with nice output and cross references, unlink/relink the file, modify sections and program
header parameter fields, hijack GOT, CTORS, DTORS, modify the symbol table, inject and remove symbols,
inject sections, remove SHT, support binaries without symtab, reconstruct the SHT . Look at
libelfsh-ref.txt for current libelfsh reference .



 1] INTRO
 2] LIBELFSH and BFD
 3] PORTABILITY
 4] MAJOR CHANGES FOR THIS VERSION
 5] VARIOUS NOTES ABOUT ELF AND ELFSH 
 6] BUGS
 7] CONTACT INFORMATION


At the moment, libelfsh.so a powerfull API with many examples programs . The binary called 'elfsh' is a 
simple viewer, displaying information on ELF objects, but its designed to become an interactive and scriptable 
ELF machine to play with executable files, shared libraries and relocatable objects using libelfsh and an 
interactive ala gdb interface .

What you can do with elfsh:

bash-2.05$ /usr/bin/elfsh 

	     There is no interactive mode implemented !

                 The ELF shell version 0.43a
		 
    Syntax: elfsh -f filename [-elf -e] [-interp -i] [-p -phdr]
    [-hexa -X] [-got -g] [-shdr -s] [-rel -r] [-notes -n] [-dyn -d] 
    [-dynsym -ds] [sym -s] [-stab -sb] [-ctors -ct] [-dtors -dt] 
    [-sort -sr a|s]
  
   -f filename            : choose the file you want to load  
   -elf    [-e]           : display the ELF header   
   -interp [-i]           : display the .interp section                     
   -phdr   [-p]           : display the program header table     
   -hexa   [-X]  regx     : display in hexa the requested object (regx required) 
   -got    [-g]  regx     : display the global offset table (GOT)           
   -shdr   [-s]  regx     : display the section header table 
   -rel    [-r]  regx     : display the relocation section(s) entries  
   -notes  [-n]  regx     : display the notes section(s) entries            
   -dyn    [-d]  regx     : display the .dynamic section entries    
   -dynsym [-ds] regx     : display the dynamic symbol table entries     
   -sym    [-st] regx     : display the symbol table entries      
   -stab   [-sb] regx     : display the stab section entries (trash ;)   
   -ctors  [-ct] regx     : display the .ctors section        
   -dtors  [-dt] regx     : display the .dtors section         
   -sort   [-sr] {a,s}    : sort symbols by address (a) or by size (s)
	   
	   Regular expressions may or may not be used ... C:-]
	   
bash-2.05$ 






Its very easy to hack elfsh because the elfshlib is very modular and calls
already exists to retreive pretty much everything you want . 



2] The mechanisms are not very similar to BFD since libelfsh is :

	. ELF specific 
	. Reverse engineering oriented 

Due to the poor ELF backend proposed by BFD, and because I really wanted to get depth into
the ELF code, the interface has been fully recoded, and libelfsh does not use BFD at all .




3] It's a beta version (0.43b) . The code seems to be okay, there's no apparent bugs, but I would 
like to get some feedback before releasing it as a final version .

The code has been developped on Linux Slackware on a Intel Pentium 
processor . It was tested on Linux Slackware 8, Linux Debian 2.2, Linux
Redhat 7.3, FreeBSD 4.4 and NetBSD 1.5.2 . Solaris port is lacking an has
been delayed since ELF64 support is lacking . OpenBSD (3.0) doesnt use ELF as its
default executable format so it wasnt fully tested on OpenBSD .


4] This version is a MAJOR update, the viewer has been enhanced, some minor bugs have 
been fixed . Some structures have been created (Elfsh32_Func, Elfsh32_Sect, Elfsh32_Notes, 
Elfsh32_Note_ent, Elfsh32_Plt_ent, etc..) . There is some major changes in the libelfsh API, 
so you should definitely check the reference again before starting a new project using it .
Check the API in libelfsh-ref.txt .



5] ELFsh in practice : Load your object file with the -f option . You can examine executable
files, shared libraries, modules, and the kernel binary if its not compressed
and if its in ELF format . You can also load an uncompressed kernel image
such as vmlinux .

For your personnal culture :
- Linux current, NetBSD current, FreeBSD current, and Solaris current use ELF .
- OSF1 (DEC alpha) uses COFF/alpha, a modified COFF format (poorly merged w/ a.out) .
- Windows (9x/NT/2K/XP) uses PE .


Notes about ELFsh bugs/strange behavour :

1. When displaying the symbol table with elfsh section symbols do not
have their name printed properly . The reason: elfsh_get_symbol_name() is called 
with a bad string table . This is a bug and has to be fixed . Note that objdump has the 
same behaviour (even a worse one since elfsh manages to print allocatable section name at least ;). 
By the way, you can display the whole list of sections with the -s option
in elfsh .

2. When displaying symbols, some symbol types are NULL . Its wierd, objdump also
also has the same behaviour . To be honest, I dont know why, i think that's a strange
gcc behaviour but I have to work on it . Tell me if you have the answer for that .





6] CONTACT


Many features are still planed (look at the TODO file) . If you have any requests (new features, 
bugtracking, comments, or just to say hello) you can mail me on : 

	mayhem@devhell.org

If you're interrested in thee subject, you can find ressources on my page :

	http://www.devhell.org/~mayhem/	

The ELFsh development started in the last days of february 2001, but I'm very busy
with school these days so it is pretty slow . I would like to thanks the reverse 
engineering research community, particulary silvio, klog, theowl and grugq
(I dont forget you ;), and of course Cristina Cifuentes because she is my heroin :>
Halvar, when can I see your code ? ;)

Enjoy !














