home *** CD-ROM | disk | FTP | other *** search
/ Amiga GigaPD 3 / Amiga_GigaPD_v3_3of3.iso / fred_fish / fish_601-700_lha / fish_674.lha / HEXTRACT / Hextract.doc < prev    next >
Text File  |  1993-06-02  |  7KB  |  176 lines
  1.  
  2.                             H E X T R A C T  V1.1 
  3.  
  4.     Hextract provides a means of quickly and easily referencing the mass of
  5.  information contained in header files.
  6.  
  7.     For programmers in C it can give you:
  8.      
  9.      Definition of any symbol
  10.      Name of header file containing the symbol.
  11.      Composition of any structure.
  12.      Definitions of structure members.
  13.      Function definitions and arguments.
  14.      Library contents.
  15.      Include.h macros.
  16.          
  17.     Additionally for programmers in Assembler, and to help dis-assembly:
  18.  
  19.      Library offsets & arg registers.
  20.      Structure offsets. 
  21.  
  22.     The data file in this release (headers.z) was constructed mainly from the
  23.    Commodore and Lattice Include_h header files issued with Version 5 of the
  24.    Lattice compiler, with additional data added from the Include_i files.
  25.    Detail of the Arp library is also included.
  26.  
  27.     OPERATION 
  28.  
  29.     Hextract can be called from both Workbench and the CLI.  There are no 
  30.    switches or variations.   The only requirement is that the executable
  31.    Hextract and the data file headers.z must be in the same directory.
  32.  
  33.     The data file at 281 KBytes is pretty substantial and to save space it
  34.    has been compressed (P-Compress) down to only 69K.  Decompression is done
  35.    automatically when Hextract is loaded.  The other effect of the size of the
  36.    file is that searching it while on a floppy disk drive would be unaccept-
  37.    ably slow (and none too quick on hard disk either); to overcome this a
  38.    temporary file (headers.t) is opened in RAM and headers.z is copied to this.
  39.    If you have plenty of space on a hard disk and prefer to hold the data file
  40.    in uncompressed form to eliminate decompression time when loading, copy the
  41.    file ram:headers.t to your hard disk (while Hextract is open), rename it 
  42.    headers.z and copy Hextract and Hextract.info to the same drawer.
  43.  
  44.     Hextract opens a window and shows the prompt "Enter symbol".  Type in the
  45.    word to be identified and press return.  Hextract is not case-sensitive, 
  46.    and recognises the AmigaDOS wildcards ? and #.  While searching the pointer
  47.    changes to a W.  A complete search will take about 30 secs on an A500, and
  48.    about 5 secs on an A3000.
  49.  
  50.     Note that ALL entries should be stripped of everything except the bare 
  51.    name.   Enter *()Apple[24] as Apple.
  52.  
  53.     To quit the programme type QUIT at the "Enter Symbol" prompt.  To quit 
  54.    while a search is in progress press CONTROL_C.
  55.  
  56.    Defines, Typedefs, structure members
  57.  
  58.     If the word appears in the relevant .h file as a #define or #typedef you
  59.    will get something like:   (MEMF_PUBLIC typed in).
  60.  
  61.        "#define MEMF_PUBLIC (1<<0)"  exec/memory.h  
  62.  
  63.     The entry extracted is shown within inverted commas, and the name of the
  64.    header file added.   
  65.     
  66.     If the word is a member of a structure you get:  (BufBuffer typed in)
  67.  
  68.        WORD  *BufBuffer 8 struct DBufPacket
  69.  
  70.     The figure 8 is the member's offset in the structure.
  71.  
  72.    Structures
  73.  
  74.     To get the composition of a structure, type in the structure name;  
  75.     for example typing in DBufPacket produces:
  76.  
  77.       struct DBufPacket  dbp_  12  graphics/gels.h 
  78.        {
  79.        WORD BufY 0  
  80.        WORD BufX 2  
  81.        struct VSprite *BufPath 4
  82.        WORD *BufBuffer 8
  83.          };
  84.  
  85.     The top line gives the full name of the structure, the prefix used when    
  86.    writing in assembler, where this differs from any .h file prefix, (for 
  87.    example the .i file would show dbp_BufY)  the size in bytes, and the 
  88.    parent header file.  In the line for each member the last figure shows the
  89.    structure offset.
  90.    
  91.    Structures with nested unions or structures are a bit more complicated. an
  92.    example is the structure MemEntry:
  93.       struct MemEntry 8 exec/memory.h
  94.        {
  95.        union {
  96.              ULONG meu_Regs 0
  97.              APTR  meu_Addr 0
  98.              } me_Un ;
  99.       "union me_Un" exec/memory.h
  100.        ULONG me_Length 4
  101.        };
  102.     
  103.     This shows a structure with two members - the union me_Un and the ULONG
  104.    me_Length.  The full name of meu_Regs will be me_Un.meu_Regs.
  105.  
  106.    Functions
  107.  
  108.     If the word is a function the form of the output will vary according to
  109.    whether it is a Lattice or Amiga library function.  Entering Open will
  110.    produce:
  111.  
  112.      "extern int open  __Args((char*,int, ))"   fcntl.h
  113.  
  114.      -30 $fffe2 -$001e  Open(name,accessMode)(D1/D2)  dos.library.h
  115.  
  116.     The equivalent ARP library entry is also given.   The first line details
  117.    the function open() in the Lattice file fcntl.h, inverted commas show that 
  118.    it is a direct quote from the file.  The second line shows the DOS function
  119.    Open() and gives the library offset in decimal, hex(complement), and hex.
  120.  
  121.    Libraries
  122.  
  123.     If the name of the Library is entered - such as Dos.library or Console.
  124.    device - the full list of functions in the library will be output.
  125.  
  126.  
  127.    If you are not sure of the spelling of the word you want to find the data
  128.   file can be decompressed and loaded into an editor for examination (if you
  129.   have sufficient memory).  You can also add any definitions of your own that 
  130.   you might want to reference, or shorten the file by deleting sections
  131.   that are of no value to you.  Note the line FFFFFF (line 4924) - this marks
  132.   the start of the library functions section and any additions must be
  133.   inserted before it.
  134.    
  135.    Some header file details have necessarily been omitted from headers.z. 
  136.   These include:
  137.  
  138.      Comments.
  139.      Macros given in the include.i files.
  140.      Proto files.
  141.      Lines beginning #IF, #IFDEF, #IFNDEF, #ENDIF, #ELSE.
  142.  
  143.    The latter may result in two or more apparently conflicting definitions
  144.   of the same item being shown - the various header files will be named so
  145.   that you can find any further information needed.    
  146.      
  147.  
  148.            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  149.  
  150.     Hextract is Freeware.  It may be copied and distributed freely and used
  151.   without charge for non_profit-making purposes.  Authority for profit-making   use should be obtained from the author below.
  152.  
  153.     No responsibility can be accepted for any loss occasioned by use of the
  154.   programme.
  155.  
  156.     This release only covers the V1.3 operating system and a V2.0 version may 
  157.   be expected in due course.  Also if someone cares to send me a complete set
  158.   of Manx header files, a Manx version of headers.z could appear.
  159.  
  160.     Comments, suggestions, bug-reports all welcome.
  161.  
  162.    Chas A. Wyndham,
  163.    1265 Canning Mills Road,
  164.    Roleystone,
  165.    WA 6111.
  166.    Australia 
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.