HT Editor
=========

   This is HT 0.6.0; please note that this is a beta version of the
program.  Therefore HT is incomplete and sometimes buggy. Enjoy
anyway...

About
=====

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

     This program comes with ABSOLUTELY NO WARRANTY
     This is free software, and you are welcome to
     redistribute it under certain conditions
     For more information please read the GNU General
     Public License, contained in the file "copying"
     If you do not have received a copy of this file along
     with this program, please write to the Free Software
     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Keys
====

   * General key bindings

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

   * Window key bindings

     Alt+F3            close window
     Ctrl+F5           resize/move mode


   * Analyser key bindings

     c                 continue code analysis at cursor
     f                 follow dword ptr at address
     n                 (re)name current address (empty string to delete)
     x                 show xrefs (search for xrefs)
     #                 edit comments
     Ctrl+A            call assembler
     Ctrl+F            goto start of current function
                       (indicated in the 2nd line)
     Ctrl+L            goto previous label
     Ctrl+T            show recursive function references



Note: HT-posix keyboard support is somewhat experimental. Be warned.

Authors
=======

   Stefan Weyergraf <stefan@weyergraf.de>

   Sebastian Biallas <sb@biallas.net>

Features
========

   Although HT is beta software and should not always be regarded as
stable, it contains some very advanced and useful features:

Supported file formats
======================

   * Win32 portable executables (PE)
          - header
          - import section
          - delay-import section
          - export section
          - resources
          - image with code/data analyser (x86 & alpha)

   * UN*X executable and linkable format (ELF)
          - header
          - section headers
          - program headers
          - symbol tables
          - image with code/data analyser (x86)

   * Win16, OS/2 new executables (NE)
          - header
          - segments
          - names
          - entrypoints
          - imported names
          - image with code/data analyser (x86)

   * UN*X common object file format (COFF)
          - header
          - image with code/data analyser (x86)

   * Win, OS/2 linear executables (LE)
          - header
          - object table
          - page table
          - image (disassembly only)

   * DOS executables (MZ)
          - header
          - relocations
          - image (disassembly only)

   * Java class files (experimental)
          - header

Code and data analyser
======================

     - finds branch sources and destinations recursively
     - finds procedure entries
     - creates labels based on this information
     - creates xref information
     - interactively analyse unexplored code (press 'c')
     - create/rename/delete labels (press 'n')
     - create/edit comments (press '#')

Target systems
==============

   HT is tested and known to work on at least the following systems:
     - DJGPP
     - GNU/Linux
     - FreeBSD
     - Win32

   HT should be portable to any POSIX-compilant OS supporting (n)curses
with almost no effort.

   Much work is done to enable HT for non-x86 systems.  Alpha, PPC, 68k
and Sparc have been successfully build and started.  These versions are
however mostly untested (broader testing anyone ?).

Configuration files
===================

System-wide configuration
-------------------------

   HT automatically creates a file to store its configuration.  It is
called `~/.htcfg' on Unices and `ht.cfg' (where ht.exe resides) on
Windows. More specifically it contains HT's registry and the *Note
Global history::.

Per file configuration
----------------------

   The analyser (for analysable files) will store its data in an extra
file called `FILENAME.htcfg', where FILENAME is the name of the
analysed file. This file contains all information to restore the
complete state of the analyser.

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 wouldn't make sense (e.g. file open).

   Although the clipboard is not preserved across 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' *Note history: Global history, which is stored and
retrieved from the config file automatically.

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.

   History entries are stored within the *Note Configuration files::,
so they can be reused when you relaunch.

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

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 `int()', `string()'
and `float()' functions to appropriate type. Try Edit->Evaluate to see
how it works...

Functions and symbols
---------------------

   You can always use the standard buildin math (`round', `sin',
`random', etc.) and string (`strcmp', `strchr', `sprintf', etc.)
functions, they work more or less like the corresponding C functions
(actually they ARE more or less wrappers for them); see `eval/eval.y'
for details (sorry but a detailed help would get outdated rather soon).
When using *Note Block operations::, or searching you have some context
depending functions and symbols; see these sections for explanation.

Block operations
================

   Block operation (Blockop) is a very powerful tool to perform
modifications on binary files. It is available in hex (i.e.
raw/uncooked) mode only.

   Blockop takes four parameters: START, END, MODE and EXPRESSION.
Blockop works as follows:

   * START: Start at the offset specified by START

   * REPEAT: Evaluate EXPRESSION and store n bytes (byte - 1,  word - 2,
     dword - 4, string - variable) or less (to match END) at the current
     offset. Stop if END has been reached. Increment current offset by
     n.  Repeat.

Special variables/functions that can be used in EXPRESSION:

`readbyte(ofs)'
     read a byte from offset OFS, returns a number

`readstring(ofs, size)'
     read SIZE bytes from offset OFS, returns a string

`i'
     contains the iteration count/index starting with 0

`o'
     contains the current offset

Searching
=========

   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:

bin: ASCII / Hex
----------------

   Enter an exact search string either via ascii characters or via
hexadecimal interpretation. This is the fastest search mode.
OPTIONS: case-insensitive.

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. `"hello world\n\0"'
OPTIONS: case-insensitive.

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
`(add|sub).+?,[78]'.  This will find all add or sub instructions with
second parameter 7 or 8.
OPTIONS: case-insensitive.

expr nonzero
------------

   This is the slowest but also most advanced search mode. The search is
successful if the entered expression evaluates to non-zero (it will be
evaluated once for every byte). In this mode there are two predefined
symbols and some functions: I is always the number of current iteration
and O stands for the current offset in file. With the functions
`readbyte(ofs)' and `readstring(ofs, size)' you may access the file's
content.

   It's easier to understand this with examples:

  1. Searching for patterns:

       a. Enter `readbyte(o) == readbyte(o+1)'
          This will search for two equal bytes ("AA", "55", "!!", etc.).

       b. Enter `(readbyte(o) == readbyte(o+1)+1) &&
          (readbyte(o)==readbyte(o+2)+2'
          This will search for three ascending bytes ("ABC", "123",
          etc).

  2. Search with special functions:

     With HT you can easily detect the RSA key in the `ADVAPI32.DLL':
     Search for `entropy(readstring(o, 64)) > 82' in expr!=0 mode, and
     you will find it very quickly. How does it work? `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 `entropy()' function is not the best of its kind, if you
     have a better one please let us know!


x86 Assembler
=============

   HT features an assembler for the x86 architecture.  It is capable of
assembling any command string, that HTs disassembler produces. I.e. it
can at least produce 386,486,Pentium + MMX + 3dnow instructions.
Assembling and disassembling is done separately using a single
compiled-in opcode table.

   If supported the assembler can be invoked in any disassembler view
by hitting CTRL+A.  If the typed assembler command is ambigous in
itself (e.g. no memory type given) or if there are multiple opcodes
possible, alternatives are presented.  If alternatives are presented HT
tries to select an alternative opcode with the same size as the opcode
that you had selected when pressing CTRL+A.

Homepage
========

The HT homepage is at `http://hte.sourceforge.net'

Downloads are available from the 'download' section.  For further
information and bug reporting look at
`http://sourceforge.net/projects/hte'

Feel free to *Note mail us: Authors..  Suggestions, criticism and
patches welcome.

