Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/497a.lha/ComSMUS_v2.2/iffar.src/IFFAR.README

Text File | 1991-04-07 | 7KB | 213 lines

iffar - IFF CAT Archiver, Release 1.4, 9/23/89

Written by:

    Karl Lehenbauer/Hackercorp
    3918 Panorama
    Missouri City, TX  77459

    Usenet:  ..uunet!sugar!karl
    Internet: [e-mail]
    BIX: kelehen

All liability is disclaimed!  This code is free.  We do not have a contract.

This software, source and binary, is released to the public domain, 5/9/88.

I ask that you retain my name as the original author in the source and
documentation if you redistribute this and that I be credited in the user
manual if iffar is redistributed with a commercial product.

Subsequent updates are also released to the public domain.

Regards,  Karl Lehenbauer @ The Hacker's Haven, Missouri City, Texas, 7/31/89


---------------------------------------------------------------------

NAME

    iffar - IFF CAT archiver

SYNOPSIS

    iffar option [posname] archive_file [IFF_file] ...

DESCRIPTION

    Iffar maintains archives of Interchange File Format (IFF) FORM and CAT
    files in a manner  that complies with the IFF CAT specification.

    IFF CAT archives should be portable to different machines.  No promises.

    The option string must start with 'd', 'q', 'r', 't' or 'x' and may
    additionally have modifiers of 'a', 'b', 'c', 'i' or 'v'.  Not all
    modifiers are valid with all options.

    The options are:

        'd'        Delete named IFF files from the CAT archive.

        'q'        Quickly append named IFF files to the CAT archive.

        'r'        Replace named IFF files in the CAT archive; append new ones.

        't'        Print a table of contents of the CAT archive.

        'x'        Extract named IFF files from the CAT archive.
                If no names are specified, all files are extracted.


    The modifiers are:
        'a'        "after", replace or append IFF files after entry in CAT
                    archive named by posname

        'b'        "before", replace or append IFF files before entry in CAT
                    archive named by posname

        'c'        Do not print a message indicating archive is being created
                    when it must be created.

        'i'        a synonym for "before"

        'v'        print verbose description of all activity
                For table of contents, prints IDs, and
                lengths of chunks within the IFF file chunks
                in the CAT archive.  It prints the contents of
                chunks that it knows to be textual and short.


    On all operations that modify the archive, except for "quick append",
    the archive will be renamed with a ".old" extension and a new archive
    will be created.

    The "quick append" option causes the named files to be added to the
    end of the archive without rewriting the archive or looking to see
    if the entry already exists.  This is to avoid quadratic behavior
    when building up an archive one or just a few entries at a time.

    Wildcards of the semi-Unix-type as supplied by Manx are provided.

    Only the basename of the specified IFF filenames will be used for
    element names within the archive.  In other words, pathnames are
    stripped from filenames to create the archive element name.
    This is also true for extracts.

EXAMPLES

    iffar x foo ram:t/bar

        would extract element "bar" from archive "foo" into file
        "ram:t/bar"

    iffar ra sounds Cabasa dh0:sounds/Snare

        would replace a FORM, CAT or LIST named Snare in the
        archive with dh0:sounds/Snare, placing Snare directly
        after Cabasa.  If Cabasa is not found in the archive,
        Snare is placed at the end.

BUGS

    The archive will be corrupted if a write error (including
    running out of disk space) occurs during "quick
    append" mode and there won't be a ".old" backup file left
    either.

    Running out of disk space leaves corrupted archives.
    For all options but "q", the ".old" backup file will contain
    the archive in its state prior to the run that blew it up.
    The program should delete the corrupted archive and restore
    the ".old" file, but it doesn't.

    A user contacted me after grabbing the 1.2 version and insisted
    that it is illegal under the IFF spec to add chunks to FORMs that
    your program doesn't understand.  If you agree with this, iffar
    must be considered broken because it adds a chunk that it
    uses to identify the embedded FORM or CAT.  iffar strips this
    chunk when extracting a file, however, but there were conflicts
    when FORMs already contained FNAM chunks.
        I have given a lot of thought to this and I believe from a
    careful reading of the spec that it is legal to add chunks to FORMs
    your program doesn't understand.  I have renamed iffar's chunk ID
    from FNAM to IFAR which should vastly reduce the possibility of a
    conflict.
        I would like to rewrite iffar to not embed the ID chunk within
    the form but rather to keep it outside the form, though still in
    an IFF manner, which would solve the problem. This would reduce the
    complexity of the program  and increase its performance.  However,
    it's  a lot of work and the archiver is useful (to me at least) as
    is, hence the 1.3 version is a spruce-up rather than a rewrite.

    iffar doesn't archive IFF LIST files properly.  They're rare.


IMPLEMENTATION NOTES

    Iffar is written to run under Manx Aztec C 3.6a for the Amiga
    under AmigaDOS version 1.3.

    My IFF archiving routines were written to be well-behaved from an
    IFF point of view; that is, they try to respect the virtual
    end-of-file defined by the size field of a chunk's header when
    diving through the chunk's subchunks.  It makes for more work to use
    the routines, but adds some certainty that the program is working
    properly.  I don't know.  The IFF spec requests that we do, so I do.

    Note that when converting your code to use a CAT file instead of
    reading several FORM files (it's about twice as fast for an
    application of mine involving about 25 files from two to ten
    kilobytes each, reading them in from floppy.), your code needs
    to either be driven by the files read from the CAT (you search
    a list of names you're looking for when you see a FORM and load
    what you want) or your code has to know what's coming from the
    CAT specifically.  I'd prefer that you do the former, of course.
    The table of contents routines (toc.c) provide a reasonable template
    for your CAT-reading application.

NOTES FOR THOSE WISHING TO PORT THE ARCHIVER

    Knock yourselves out.  The code is written using standard C library
    calls, with the exception of calls to "scdir", which Manx uses as
    a means of expanding wildcards.  If you get it to work on a different
    system, such as Unix System V, please send me a copy, preferably
    with #ifdefs so the Manx stuff still works.  Ultimately, I think an
    alternative "_main" startup routine should be written for the Amiga
    that expands wildcards inline to provide an argc and argv as they
    would look on Unix after the shell had expanded all the wildcards.


REVISION HISTORY

4/25/88, version 1.1

    Initial version - never distributed, as far as I know

5/9/88, version 1.2

    Made 'r' (replace) option create the archive if it isn't there.

    Fixed bug that caused the IFF reader to get lost when doing
      a verbose table of contents on certain archives.

    Flattened the source directory structure.

    Updated the documentation.

7/31/89, version 1.3

    Changed the chunk type iffar uses as the name for embedded FORMs and
    CATs from FNAM to IFAR to reduce conflict with certain FORMs.

    Updated the documentation.

    Compiled and tested under AmigaDOS 1.3.


9/23/89, version 1.4

    Fixed bug where some archive entry names would be truncated


-----------------------------------------------------------------------------