\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename ht.info
@settitle HT Editor Documentation
@iftex
@afourpaper
@end iftex
@c %**end of header

@ifinfo
@format
START-INFO-DIR-ENTRY
* ht: (ht.info).             HT Editor.
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@iftex
@c @finalout
@end iftex

@ifinfo
This file documents the HT Editor.

@c 
Copyright @copyright{} 1999-2014 The HT authors. @*
@xref{Authors, The HT Authors, The HT Authors},
for a list of the copyright holders.

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore

@sp 4
Trademarks are the property of their respective owners, which may
be registered in certain jurisdictions.
@end ifinfo

@c begin chapters on right pages
@setchapternewpage odd

@titlepage

@title HT Manual
@subtitle Edition 2.1.0, September 2014

@author Stefan Weyergraf, Sebastian Biallas
@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll

Copyright @copyright{} 1999-2014 The HT authors. @*
@xref{Authors, The HT Authors, The HT Authors},
for a list of the copyright holders.

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@sp 4
Trademarks are the property of their respective owners, which may
be registered in certain jurisdictions.
@end titlepage



@c
@c SETTINGS, DEFINES, MACROS
@c

@macro htversion
2.1.0
@end macro

@macro hturl
@uref{http://hte.sourceforge.net}
@end macro

@macro htsfurl
@uref{http://sourceforge.net/projects/hte}
@end macro

@macro none
@end macro

@c
@c TOP NODE
@c
@node Top, , (dir), (dir)
@unnumberedsec HT Editor

@noindent
This is HT @htversion{};
Have fun@dots{}

@menu
* About::
* Key bindings::
* Features::
* Authors::
* Where to download?::
@end menu

@node About, , Top, Top
@unnumberedsec About

@noindent
This program is a file viewer, editor and analyzer for text, binary, and (especially) executable files.

@quotation
@noindent
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as published by
the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
@end quotation

@node Key bindings, , Top, Top
@unnumberedsec Key bindings

@macro keytablecolumns
.25 .75
@end macro

@itemize @bullet

@item
General key bindings

@multitable @columnfractions .25 .75
@item Return
@tab follow link (if applicable)
@item Backspace
@tab undo ``follow link''
@item Space/F6
@tab choose view mode
@item Alt+[1-9]
@tab select window
@item Alt+0
@tab select window list
@item Ctrl+Left/Right
@tab scroll left/right
@item Cursor keys
@tab move around
@item Page Up/Down
@tab next/prev page
@item Alt+S
@tab toggle select
@item Ctrl+Ins/Alt+C
@tab copy
@item Shift+Ins/Alt+V
@tab insert
@item Ctrl+Del/Alt+D
@tab delete
@item Shift+Del/Alt+X
@tab cut
@end multitable

@item
Window key bindings

@multitable @columnfractions .25 .75
@item Alt+F3/Ctrl+W
@tab close window
@item Ctrl+F5
@tab resize/move mode
@item
@tab (in resize/move mode only:)
@item Space
@tab toggle resize/move mode
@item Cursor keys
@tab resize/move window
@item Escape/Return/Ctrl+F5
@tab leave resize/move mode
@end multitable

@item
Analyser key bindings

@multitable @columnfractions .25 .75
@item c                    
@tab continue code analysis at cursor
@item f                    
@tab follow dword ptr at address
@item n                    
@tab name current address 
(empty string to delete)
@item x                    
@tab show xrefs (search for xrefs)
@item #                    
@tab edit comments
@item s
@tab define a string
@item i
@tab define an integer (32bit)
@item h
@tab define a halfword (16bit)
@item b
@tab define a byte (8bit)
@item Ctrl+A               
@tab call assembler
@item Ctrl+F               
@tab goto start of current function@*
(indicated in the 2nd line)
@item Ctrl+L               
@tab goto previous label
@item Ctrl+T               
@tab show recursive function references

@end multitable

@end itemize

@sp 1
@noindent
Note: Some keys don't work in HT-posix. Try using Escape
instead of Control or something...

@node Authors, , Top, Top
@unnumberedsec Authors

@itemize @bullet

@item Stefan Weyergraf

@item Sebastian Biallas @email{sb@@biallas.net}
@end itemize

@node Features, , Top, Top
@unnumberedsec Features

HT contains some very advanced and useful features, which you
should carefully inspect:

@menu
* General features::
* Configuration files::
* Clipboard::
* Global history::
* Expression evaluation::
* Block operations::
* Search and its different modes::
* Command line options::
@end menu

@node General features, , Features, Features
@unnumberedsec General features

@enumerate 1
@item
Supported file formats
@itemize @bullet
@item 
common object file format (COFF/XCOFF32)
@itemize @w
@item 
- header @*
- image with code/data analyser (x86)
@end itemize
@item 
executable and linkable format (ELF)
@itemize @w
@item
- header @*
- section headers @*
- program headers @*
- symbol tables @*
- image with code/data analyser (x86, AMD64, Alpha, PowerPC, ARM, AVR) and relocations
@end itemize
@item 
linear executables (LE)
@itemize @w
@item
- header @*
- VxD descriptor @*
- object table @*
- page table @*
- image with code/data analyser (x86) @*
- auto-relocation layer (only internal refs for now)
@end itemize
@item 
standard dos executables (MZ)
@itemize @w
@item
- header @*
- relocations @*
- image (disassembly only)
@end itemize
@item 
new executables (NE)
@itemize @w
@item
- header @*
- segments @*
- names @*
- entrypoints @*
- image with code/data analyser (x86) @*
- auto-relocation layer (pretty complete)
@end itemize
@item 
portable executables (PE32, PE64)
@itemize @w
@item
- header @*
- import section @*
- delay-import section @*
- export section @*
- resources @*
- image with code/data analyser (x86, AMD64, PowerPC, Alpha, ARM) @*
- preliminary support for .net executables
@end itemize
@item 
java class files (CLASS)
@itemize @w
@item
- header @*
- image with code/data analyser (java bytecode disassembler)
@end itemize
@item 
Mach exe/link format (MachO)
@itemize @w
@item
- header @*
- image with code/data analyser (x86, AMD64, PowerPC, ARM) @*
@end itemize
@item 
X-Box executable (XBE)
@itemize @w
@item
- header @*
- imports @*
- image with code/data analyser (x86) @*
@end itemize
@item 
Flat (FLT)
@itemize @w
@item
- header @*
- image with data analyser (no disassembler yet) @*
@end itemize
@item 
PowerPC executable format (PEF)
@itemize @w
@item
- header @*
- imports
- image with code/data analyser (PowerPC) @*
@end itemize
@item
Still some to be implemented (M$-OBJ, ARCH, LX)
@end itemize
@item
Code & Data Analyser
@itemize @w
- finds branch sources and destinations recursively @*
- finds procedure entries @*
- creates labels based on this information @*
- creates xref information @*
- allows to interactively analyse unexplored code (press 'c') @*
- allows to create/rename/delete labels (press 'n') @*
- allows to create/edit comments (press '#')
@end itemize
@item
Target systems
@itemize @w
- GNU/Linux @*
- FreeBSD @*
- Win32
@end itemize
@end enumerate

@node Configuration files, , Features, Features
@unnumberedsec Configuration files

@unnumberedsubsec Global configuration
HT automatically creates a file to store its configuration.
It is called @file{~/.htcfg2} on Unices and @file{ht.cfg2} (where 
ht.exe resides) on Windows. More specifically it contains HT's registry 
and the @xref{Global history}.

@unnumberedsubsec Per file configuration
The analyser (for analysable files) will be stored in an extra file called 
@file{FILENAME.htcfg}, where FILENAME is the analysed file. This file contains
all information to restore the complete state of the analyser.

@node Clipboard, , Features, Features
@unnumberedsec Clipboard

All open files and dialogs use the common clipboard, where all
copied and cut text or binary data is stored. Clipboard operations are 
normally binary safe, that means you can copy some binary data out of a
file and paste it into an input line. Exceptions are only the \0 character
(binary null), it will be converted to a space in places where it would not
make sense (e.g. file open). 

Although the clipboard won't be saved between different HT sessions
(ie. you will loose it when exiting HT), you can either save and load it
or part of it manually (via Edit->paste into/copy from file) or rely on
the input lines' @xref{Global history, history}, which is stored and
retrieved from the config file automatically.

@node Global history, , Features, Features
@unnumberedsec Global history

HTs history system is global, which means that you can use it for all open
files. Histories are also grouped by their context. I.e. file-related and 
regex-search-related dialogs have their own history (who would want to 
open "[0-9][0-9a-z]+" anyway?).

History entries are stored within the @xref{Configuration files}, so they
can be reused when you relaunch.

You can delete a history entry by pressing DEL inside the history popup.

@node Expression evaluation, , Features, Features
@unnumberedsec Expression evaluation

HT contains a very powerful expression evaluator which is used in all dialogs
where expressions are expected. These are mainly blockoperation, goto,
search and of course evaluate itself (Edit->Evaluate).

You can use all standard math operators (+ - / * % **), logical operators
(! && || ^^), relational operators (== != < > <= >=),
bit operators (~ & | ^), string operators (. for concatenation),
parenthesis, the ternary operator (a?b:c), functions and symbols 
(both depending on context).

The evaluator uses integer, string and float types depending on context. You
can always convert a result via the @code{int()}, @code{string()} and @code{float()} functions
to appropriate type. Try Edit->Evaluate to see how it works@dots{}

@unnumberedsubsec Functions and symbols
You can always use the standard built-in math (@code{round}, @code{sin}, @code{random}, etc.) and
string (@code{strcmp}, @code{strchr}, @code{sprintf}, etc.) functions, they work more or less like the corresponding
C functions (actually they ARE more or less wrappers for them); see @file{eval/eval.y} for 
details (sorry but a detailed help would get outdated rather soon).

The symbol _ always refers to the last result.
If you are in a hex buffer, the variable @code{first} contains the offset of the first byte and the variable
@code{last} contains the offset of the last byte. This is useful, for instance, if you want to jump to the last byte of a file.

When using @xref{Block operations}, or searching you have some 
context depending functions and symbols; see these sections for explanation.

@node Block operations, , Features, Features
@unnumberedsec Block operations

Block operation (Blockop) is a very powerful tool to perform modifications
on binary files. It is available in hex viewer only.

Blockop takes four parameters: @var{start}, @var{end}, @var{mode} and
@var{expression}. Blockop works as follows:

@itemize @bullet
@item
START: Start at the offset specified by @var{start}
@item
REPEAT: Evaluate @var{expression} and store n bytes (1 - byte, 2 - word,
4 - dword, variable - string) at the current offset. Increment current offset
by n. Stop if @var{end} has been reached.
@end itemize

@noindent
Special variables/functions that can be used in @var{expression}:

@table @code
@item readbyte(ofs)
read a byte from offset @var{ofs}, returns a number
@item readstring(ofs, size)
read @var{size} bytes from offset @var{ofs}, returns a string
@item i
contains the iteration count/index starting with 0
@item o
contains the current offset
@end table

@node Search and its different modes, , Features, Features
@unnumberedsec Search and its different modes

The search function is one of the most advanced functions of HT.
It is invoked through F7, Shift-F7 continues a search from cursor.
Depending on context (ie. file type and mode) the following modes are enabled:

@unnumberedsubsec bin: ASCII / Hex
Enter an exact search string either via ascii characters or via hexadecimal
interpretation. This is the fastest search mode. You may specify a 
case-insensitive search.

@unnumberedsubsec bin: eval str
Enter an expression, it will be evaluated ONCE (difference to the 4th mode),
and HT will then search for the result-string. This is pretty useful when
searching for intermixed text and control-chars/binary, e.g. @code{"hello world\n\0"}

@unnumberedsubsec display: regex
As the prefix indicates, this search doesn't search in the binary file but
in the display on screen. HT searches for a regular expression so this can
be very powerful, e.g. in PE/Image you can search for @code{(add|sub).+?,\ [78]$}.
This will find all add or sub instructions with second parameter 7 or 8.

@unnumberedsubsec expr nonzero
This is the slowest but also most advanced search mode. Enter an expression
and the search stops if this expression evaluates to non-zero (it will be 
evaluated on every byte). In this mode there are two predefined symbols
and some functions: @var{i} is always the number of current iteration and
@var{o} stands for the current offset in file. With the functions @code{readbyte(ofs)}
and @code{readstring(ofs, size)} you access the file's content.

It's easier to understand this with examples:

@enumerate 1
@item
Searching for patterns: 

@enumerate a
@item
Enter @code{readbyte(o) == readbyte(o+1)}@*
This will search for two equal bytes ("AA", "55", "!!", etc.).
@item
Enter @code{(readbyte(o) == readbyte(o+1)-1) && (readbyte(o)==readbyte(o+2)-2)}@*
This will search for three ascending bytes ("ABC", "123", etc).
@end enumerate

@item
Search with special functions:

With HT you can easily detect the RSA key in the @file{ADVAPI32.DLL}:
Search for @code{entropy(readstring(o, 64)) > 82} in expr!=0 mode, and you will
find it very quickly. How does it work? @code{readstring(o, 64)} reads a 64 byte string
from current offset and entropy calculates the entropy ("randomness") of a string (result is 0..100).
So the search stops if a entropy greater than 82% (guessed value)
is encountered, which normally indicates packed or encryted data.

Note: the @code{entropy()} function is not the best of its kind, if you know of a better
one please let us know!

@end enumerate

@node Command line options, , Features, Features
@unnumberedsec Command line options

@multitable @columnfractions .10 .20 .70

@item 
@code{--}
@tab

@tab
treat all additional parameters as file names

@item 
@code{-v}
@tab
@code{--version}
@tab
show version and copyright on console

@item
@code{-h}
@tab
@code{--help}
@tab
show help

@item
@code{-t}
@tab
@code{--text}
@tab
load file(s) in text editor mode

@item
@code{-b}
@tab
@code{--bin}
@tab
load file(s) in hex editor mode


@item
@code{-a}
@tab
@code{--auto}
@tab
try to guess file type
@end multitable

@node Where to download?, , Top, Top
@unnumberedsec Where to download?

@noindent
The HT homepage is located at 
@hturl{}

@noindent
Downloads are available from the 'download' section. 
Please also take a look at
@htsfurl{}

@ifinfo
@contents
@end ifinfo
@bye