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