home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Frozen Fish 2: PC
/
frozenfish_august_1995.bin
/
bbs
/
d07xx
/
d0744.lha
/
Hextract
/
Hextract.doc
< prev
next >
Wrap
Text File
|
1992-10-12
|
8KB
|
188 lines
H E X T R A C T V1.2
Hextract
provides a means of quickly and easily referencing the mass of
information contained in header files.
For programmers in C it can give :
Definition of any symbol
Name of header file containing the symbol.
Composition of any structure.
Definitions of structure members.
Function definitions and arguments.
Library contents.
Include.h macros.
Additionally for programmers in Assembler, and to help dis-assembly:
Library offsets & arg registers.
Structure offsets.
The data file in this release (headers.z) was constructed mainly from the
Commodore and Lattice Include_h header files issued with Version 5 of the
Lattice compiler, with additional data added from the Include_i files.
Detail of the Arp library is also included.
OPERATION
Hextract
can be called from Workbench or the CLI. The only general
requirement is that the executable
Hextract
and the data file
headers.z
must
be in the same directory.
From a CLI the normal call is just "
Hextract"
or "
Run Hextract"
. There is
one switch - if you call "
Hextract <file>
" Hextract will open normally and
a decompressed copy of the data file will be placed in <file>
.
The data file at 287 KBytes is pretty substantial and to save space it
has been compressed (P-Compress) down to only 72K. Decompression is done
automatically when Hextract is loaded. If you have plenty of space on a
hard disk and prefer to hold the data file in uncompressed form to eliminate
decompression time when loading, put a decompressed copy of it on the hard
disk, rename it
headers.z
and copy Hextract and Hextract.info to the
same drawer.
Hextract
opens a small window and shows the prompt "Enter symbol". Type in
the word to be identified and press
return
. Hextract is not case-sensitive
and recognises the AmigaDOS wildcard
?
. A full-screen output window
matching your current display will then be opened. While searching the
pointer changes to a
W
. A complete search will take about 11 secs on an
A500, and 2 secs on an A3000.
Note that ALL entries should be stripped of everything except the bare
name & any preceding underscore. Enter *()Apple[24] as Apple.
You can continue to use the full window for further entries, or return
to the small one by entering
OK
.
To quit the programme type
QUIT
at the "Enter Symbol" prompt. To quit
while a search is in progress press
CONTROL_C
.
Defines, Typedefs, structure members
If the word appears in the relevant .h file as a #define or #typedef you
will get something like: (
MEMF_PUBLIC
typed in).
"#define MEMF_PUBLIC (1<<0)" exec/memory.h
The entry extracted is shown within inverted commas, and the name of the
header file added.
If the word is a member of a structure you get: (
BufBuffer
typed in)
WORD *BufBuffer 8 struct DBufPacket
The figure 8 is the member's offset in the structure.
Structures
To get the composition of a structure, type in the structure name;
for example typing in
DBufPacket
produces:
struct DBufPacket dbp_ 12 graphics/gels.h
{
WORD BufY 0
WORD BufX 2
struct VSprite *BufPath 4
WORD *BufBuffer 8
};
The top line gives the full name of the structure, the prefix used when
writing in assembler, where this differs from any .h file prefix, (for
example the .i file would show
dbp_BufY
) the size in bytes, and the
parent header file. In the line for each member the last figure shows the
structure offset; if over 10 it will be shown in both decimal and hex.
Structures with nested unions or structures are a bit more complicated. an
example is the structure
MemEntry
:
struct MemEntry 8 exec/memory.h
{
union {
ULONG meu_Regs 0
APTR meu_Addr 0
} me_Un ;
"union me_Un" exec/memory.h
ULONG me_Length 4
};
This shows a structure with two members - the union me_Un and the ULONG
me_Length. The full name of meu_Regs will be
me_Un.meu_Regs
.
Functions
If the word is a function the form of the output will vary according to
whether it is a Lattice or Amiga library function. Entering
Open
will
produce:
"extern int open __Args((char*,int, ))" fcntl.h
-30 $fffe2 -$001e Open(name,accessMode)(D1/D2) dos.library.h
The equivalent ARP library entry is also given. The first line details
the function
open()
in the Lattice file fcntl.h, inverted commas show that
it is a direct quote from the file. The second line shows the DOS function
Open()
and gives the library offset in decimal, hex(complement), and hex.
Libraries
If the name of the Library is entered - such as
Dos.library
or
Console.
device
- the full list of functions in the library will be output.
If you are not sure of the spelling of the word you want a decompressed copy
of headers.z can be loaded into an editor for examination (if you have
sufficient memory). You can also add any definitions of your own that you
might want to reference, or shorten the file by deleting sections that are of
no value to you. Note the line FF (line 4924) - this marks the start of the
library functions section and any non-library additions must be inserted
before it. Re-compress the file with
P-Compress
(Fish #595).
Some header file details have necessarily been omitted from
headers.z
.
These include:
Comments.
Macros given in the include.i files.
Proto files.
Lines beginning #IF, #IFDEF, #IFNDEF, #ENDIF, #ELSE.
The latter may result in two or more apparently conflicting definitions
of the same item being shown - the various header files will be named so
that you can find any further information needed.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Hextract is Freeware. It may be copied and distributed freely and used
without charge for non_profit-making purposes. Authority for profit-making
use should be obtained from the author below.
You may use the data file "headers.z" in your programmes, but please note
that the preparation, formatting and checking of this file accounted for
most of the work in Hextract, so please clearly say where you got it.
No responsibility can be accepted for any loss occasioned by use of the
programme.
This release only covers the V1.3 operating system and a V2.0 version may
be expected in due course.
Comments, suggestions, bug-reports all welcome. (Many thanks to D.W Reisig
of The Netherlands for his comments and suggestions) .
Chas A. Wyndham,
1265 Canning Mills Road,
Roleystone,
WA 6111.
Australia