home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 1 / GoldFishApril1994_CD1.img / d1xx / d162 / iffar / readme < prev    next >
Text File  |  1988-10-02  |  6KB  |  172 lines
  1. iffar - IFF CAT Archiver, Release 1.2, 5/9/88
  2.  
  3. Written by: 
  4.  
  5.     Karl Lehenbauer
  6.     3918 Panorama
  7.     Missouri City, TX  77459
  8.     usenet:  ..uunet!nuchat!sugar!karl  or  ..bellcore!tness7!sugar!karl
  9.     BIX: kelehen
  10.  
  11. All liability is disclaimed!  This code is free.  We do not have a contract.
  12.  
  13. This software, source and binary, is released to the public domain, 5/9/88.
  14.  
  15. I ask that you retain my name as the original author in the source and
  16. documentation if you redistribute this and that I be credited in the user 
  17. manual if iffar is redistributed with a commercial product.
  18.  
  19. Regards,  Karl Lehenbauer @ The Hacker's Haven,  Missouri City, Texas, 5/9/88
  20.  
  21. ---------------------------------------------------------------------
  22.  
  23. NAME
  24.  
  25.     iffar - IFF CAT archiver
  26.  
  27. SYNOPSIS
  28.  
  29.     iffar option [posname] archive_file [IFF_file] ...
  30.  
  31. DESCRIPTION
  32.  
  33. Iffar maintains archives of Interchange File Format (IFF) FORM, CAT 
  34. and LIST  files in a manner  that complies with the IFF CAT specification.
  35.  
  36. IFF CAT archives should be portable to different machines.  No promises.
  37.  
  38. The option string must start with 'd', 'q', 'r', 't' or 'x' and may
  39. additionally have modifiers of 'a', 'b', 'c', 'i' or 'v'.  Not all
  40. modifiers are valid with all options.
  41.  
  42. The options are:
  43.  
  44.     'd'        Delete named IFF files from the CAT archive.
  45.  
  46.     'q'        Quickly append named IFF files to the CAT archive.
  47.  
  48.     'r'        Replace named IFF files in the CAT archive;
  49.                         append new ones.
  50.  
  51.     't'        Print a table of contents of the CAT archive.
  52.  
  53.     'x'        Extract named IFF files from the CAT archive.
  54.             If no names are specified, all files are extracted.
  55.  
  56.  
  57. The modifiers are:
  58.  
  59.     'a'        "after", replace or append IFF files after entry
  60.              in CAT    archive named by posname 
  61.  
  62.     'b'        "before", replace or append IFF files before entry
  63.             in CAT archive named by posname
  64.  
  65.     'c'        Do not print a message indicating archive is being
  66.             created    when it must be created.
  67.  
  68.     'i'        a synonym for "before"
  69.  
  70.     'v'        print verbose description of all activity
  71.             For table of contents, prints IDs, and
  72.             lengths of chunks within the IFF file chunks
  73.             in the CAT archive.  It prints the contents of
  74.             chunks that it knows to be textual and short.
  75.  
  76.  
  77.     On all operations that modify the archive, except for "quick append",
  78.     the archive will be renamed with a ".old" extension and a new archive
  79.     will be created.
  80.  
  81.     The "quick append" option causes the named files to be added to the
  82.     end of the archive without rewriting the archive or looking to see
  83.     if the entry already exists.  This is to avoid quadratic behavior
  84.     when building up an archive one or just a few entries at a time.
  85.  
  86.     Wildcards of the semi-Unix-type as supplied by Manx are provided.
  87.  
  88.     Only the basename of the specified IFF filenames will be used for
  89.     element names within the archive.  In other words, pathnames are
  90.     stripped from filenames to create the archive element name.
  91.     This is also true for extracts.  
  92.     
  93. EXAMPLES
  94.  
  95.     iffar x foo ram:t/bar
  96.  
  97.         would extract element "bar" from archive "foo" into file 
  98.         "ram:t/bar"
  99.         
  100.     iffar ra sounds Cabasa dh0:sounds/Snare
  101.     
  102.         would replace a FORM, CAT or LIST named Snare in the 
  103.         archive with dh0:sounds/Snare, placing Snare directly 
  104.         after Cabasa.  If Cabasa is not found in the archive,
  105.         Snare is placed at the end.
  106.  
  107. BUGS
  108.  
  109.     The archive will be corrupted if a write error (including
  110.     running out of disk space) occurs during "quick 
  111.     append" mode and there won't be a ".old" backup file.
  112.  
  113.     Running out of disk space leaves corrupted archives.
  114.     For all options but "q" the ".old" backup file will contain
  115.     the archive in its state prior to the run that blew it up.
  116.     The program should delete the corrupted archive and restore 
  117.     the ".old" file, but it doesn't.
  118.  
  119. IMPLEMENTATION NOTES
  120.  
  121.     Iffar is written to run under Manx Aztec C 3.6a for the Amiga
  122.     under AmigaDOS version 1.2.
  123.  
  124.     My IFF archiving routines were written to be well-behaved from an 
  125.     IFF point of view; that is, they try to respect the virtual 
  126.     end-of-file defined by the size field of a chunk's header when 
  127.     diving through the chunk's subchunks.  It makes for more work to use
  128.     the routines, but adds some certainty that the program is working
  129.     properly.  I don't know.  The IFF spec requests that we do, so I do.
  130.  
  131.     Note that when converting your code to use a CAT file instead of
  132.     reading several FORM files (it's about twice as fast for an
  133.     application of mine involving about 25 files from two to ten
  134.     kilobytes each, reading them in from floppy.), your code needs 
  135.     to either be driven by the files  read from the CAT (you search 
  136.     a list of names you're looking for when you see a FORM and load 
  137.     what you want) or your code has to know what's coming from the 
  138.     CAT specifically.  I'd prefer that you do the former, of course.
  139.     The table of contents routines (toc.c) provide a reasonable template 
  140.     for your CAT-reading application.
  141.  
  142. NOTES FOR THOSE WISHING TO PORT THE ARCHIVER
  143.  
  144.     Knock yourselves out.  The code is written using standard C library
  145.     calls, with the exception of calls to "scdir", which Manx uses as
  146.     a means of expanding wildcards.  If you get it to work on a different
  147.     system, such as Unix System/V, please send me a copy, preferably
  148.     with #ifdefs so the Manx stuff still works.  Ultimately, I think an
  149.     alternative "_main" startup routine should be written for the Amiga
  150.     that expands wildcards inline to provide an argc and argv as they
  151.     would look on Unix after the shell had expanded all the wildcards.
  152.  
  153.  
  154. REVISION HISTORY
  155.  
  156. 4/25/88, version 1.1
  157.  
  158.     Initial version - never distributed, as far as I know
  159.  
  160. 5/9/88, version 1.2
  161.  
  162.     Made 'r' (replace) option create the archive if it isn't there.
  163.  
  164.     Fixed bug that caused the IFF reader to get lost when doing
  165.       a verbose table of contents on certain archives.
  166.  
  167.     Flattened the source directory structure.
  168.  
  169.     Updated the documentation.
  170.  
  171. -----------------------------------------------------------------------------
  172.