## NuFX Specification -- Final Revision 3

Back to nulib.com library

This is an older version of the specification. Please use the File Type Note instead.

     -------------------------------------------------------------------------------
     |   The New Archive Standard for the Apple II -- "NuFX" -- NuFile eXchange    |
     -------------------------------------------------------------------------------

                     NuFX Documentation - 12/2/88 by Andy Nicholas
                           Final Revision Three - 2/3/89

                       Please distribute as widely as possible

     Send questions/comments to:

     Paper Bag Productions          CSNET: nicholaA@moravian.edu
     c/o Andy Nicholas           InterNET: nicholaA%batman.moravian.edu@relay.cs.net
     Box 435                               nicholaA@batman.moravian.edu.csnet
     Moravian College             ProLine: andyn@pro-sol.cts.com     [619-670-5379]
     Bethlehem, PA  18018    AppleLink PE: ShrinkIt

     NuFX Documentation  2/3/89                             - Page 2 -

     Preface
     -------

     The first copy of this proposal that was circulated was preliminary
     revision 10.   Since then I have had many requests for a more flexible
     solution to the archival problem.  To do so meant the removal of such
     features as the alignment to 128-byte boundaries of all data blocks and
     so forth, and the re-definition of the header block so that it is less rigid
     in its format (extensible).

     To do this makes it at least a factor more complex for programs which can
     extract records from NuFX archives on-the-fly (such as telecommunications
     programs).  While this may be seen as a hardship by some, I believe the
     additional power provided by all formats after revision 10 justifies the
     additional complexity.  Standalone utility programs should have no problems
     adjusting to the new format.

     This final revision of the documentation fixes the master_header's size
     at 48 bytes, eliminates the archive_create_program and archive_mod_program
     fields, increases the size of the access field to a longword, and introduces
     a new name for the archive, NFX, or NuFX, for "NuFile eXchange."

     I am also almost finished an archive program which places files or disks
     into NuFX archives using dynamic LZW compression, ShrinkIt.  Any reference
     to ShrinkIt in the text is a reference to this program.

     Final Rev 2 corrects the all the algorithms to include the length of the
     thread list in their calculations, includes some notes on how to properly
     include threads and directories, and standardizes on the use of "NuFX" to
     describe the archive name so as to distinguish it from Sun Microsystems'
     "NFS" network product.

     Final Rev 3 changes some of the terminology used, changes the date labels
     to xx_when instead of xxx_date_time, assigns the resource_fork of a file
     to be stored as a thread_kind in a data_thread instead of having it's own
     thread available.  An attempt at further clarity has been undertaken.

     andy (2/3/89)

     NuFX Documentation  2/3/89                             - Page 3 -

     History
     -------

     The Apple II community has always been sorely lacking a well-defined method
     for archiving files.  NuFX is an attempt to rectify the situation by providing
     for a flexible, consistent standard for archiving files, disks, and other
     computer medium.

     The Binary II standard, authored by Gary B. Little, for placing multiple files
     within a single file has been rendered obsolete by the (now) recent release of
     GS/OS(tm) which provides access to multiple filing systems.  Since GS/OS can
     (or will) use HFS files, Binary II does NOT provide for:

     o  filenames larger than 64 characters
        (GS/OS can create 8000 character filenames)

     o  a convenient way to add to, remove from, and other ways work on an archive.

     o  including HFS-style files which contain resource forks.

     o  including of entire disk images.

     o  including messages along with a file.

     o  a convenient way to represent that a file is compressed or encrypted by
         a specific application.  (an excess secondary header must be attached to
         the beginning of files, such is the case with SQueezed files)

     o  a true archive standard.  Binary II's original intent was to make transfer
         of Apple II files from local machines to large information services like
         The Source, Delphi, CompuServe, and GEnie, possible.  Otherwise, a file's
         attribute information would be lost.  Binary II is now being stretched
         beyond what it was originally meant to do.

     o  no support for multiple data threads or structures.

     Adding all of these features to the existing Binary II standard would not only
     be nerve-racking, but nearly impossible without violating the existing standard
     and causing a great deal of confusion (ie, "did you say it was Binary II, first
     revision or the second one?")  Although Binary II is flexible, it is simply
     unable to address all of these concerns without alienating existing Binary II
     extraction programs.

     So, to provide some differentiation between standards and provide a better
     functioning format, I have defined a new standard called "NuFX" (NuFile
     eXchange for the Apple II).  NuFX fixes the problems that Apple IIgs(tm)
     users would soon be experiencing as other filing systems become available for
     GS/OS(tm).  I am trying to stop a set of problems before they have a chance to
     develop.  NuFX provides all of the features of Binary II, but doesn't stop
     there...  it goes farther to allow the user the ultimate in flexibility,
     usefulness and performance.

     NuFX Documentation  2/3/89                             - Page 4 -

     Implementation
     --------------

     The basic structure of a NuFX archive is as follows:

                     [First record]                    [Next Record]
     +---------------------------------------------------------------------------+
     | Master Header | Header | Data  . . . . . . . .  | Header | Data  . . . .  |
     +---------------------------------------------------------------------------+

     A single master header block contains values which describe the entire archive
     (those of you who are into structured programming can consider them archive
     globals).  Each of the succeeding header blocks contain only information about
     the record they precede (consider them archive locals).

     Each header block may be followed by a series of "threads."  Each thread may
     be a portion of data, a message, the resource part of an extended file, a
     control sequence for a NuFX utility program, or almost any sort of
     sequential data.  The number of threads is described as a longword (32-bit
     word), so it is also possible to properly archive and store the data
     portions of sparse files.

     NuFX Documentation  2/3/89                             - Page 5 -

     Master header block contents:

     All word and double-word values are byte-reversed.

     Offset  Length  Content
     ------  ------  ---------------------------------------------------------------
     +0      1       $4E  Master ID Byte #1
     +1      1       $F5  Master ID Byte #2
     +2      1       $46  Master ID Byte #3   spells the word "NuFile" in
     +3      1       $E9  Master ID Byte #4   alternating ASCII (high, low) for
     +4      1       $6C  Master ID Byte #5   uniqueness.
     +5      1       $E5  Master ID Byte #6

     +6      2       master_crc

                     16-bit CRC of the remaining fields in this block.
                     (bytes +8 through +47)

                     Any programs which modify the master header block *MUST*
                     recalculate the CRC for the master header.

     +8      4       total_records

                     Total number of records in this archive file.

                     It is possible to chain multiple records (Files or
                     Disks) together.  It is also possible to chain
                     different types of records together (Files and
                     Disks mixed).

     NuFX Documentation  2/3/89                             - Page 6 -

     +12     8       archive_create_when

                     The date and time on which this archive was initially
                     created.  This field should never be changed once initially
                     written.

                     The format of this field is as follows:

                     +12     second - 0 through 59
                     +13     minute - 0 through 59
                     +14     hour - 0 through 23
                     +15     current Year minus 1900
                     +16     day - 0 through 30
                     +17     month - 0 through 11, with 0=January
                     +18     filler byte - reserved must be null (00).
                     +19     weekDay - 1 through 7, with 1=Sunday

                     The format of this field is identical to that described
                     in the _ReadTimeHex ($0D03) call described on page 14-14
                     of the Apple_IIgs_Toolbox_Reference:_Volume_1.

                     If the date is not known, or is unable to be calculated, this
                     field should be set to null (00).  If the weekDay is not
                     known, or is unable to be calculated, this field should be
                     set to null (00).

     +20     8       archive_mod_when

                     The date of the last modification to this archive. This field
                     should be changed every time a change is made to any of the
                     records in the archive.

                     The format of this field is as follows:

                     +20     second - 0 through 59
                     +21     minute - 0 through 59
                     +22     hour - 0 through 23
                     +23     current Year minus 1900
                     +24     day - 0 through 30
                     +25     month - 0 through 11, with 0=January
                     +26     filler byte - reserved, must be null (00).
                     +27     weekDay - 1 through 7, with 1=Sunday

                     The format of this field is identical to that described
                     in the _ReadTimeHex ($0D03) call described on page 14-14
                     of the Apple_IIgs_Toolbox_Reference:_Volume_1.

                     If the date is not known, or is unable to be calculated, this
                     field should be set to null (00).  If the weekDay is not
                     known, or is unable to be calculated, this field should be
                     set to null (00).

     NuFX Documentation  2/3/89                             - Page 7 -

     +28
      .
      .              *** RESERVED, MUST BE SET TO NULL (00) ***
      .              Do NOT use any of these fields.
      .
     +47

     NuFX Documentation  2/3/89                             - Page 8 -

     The following header block must precede each record within the NuFX archive.
     The cyclic redundancy check (CRC) has been provided to detect archives which
     have possibly been corrupted.  The only time the CRC should be included in
     in a block is for the master header and for each of the regular header blocks.
     The CRC functions to ensure reliability and record integrity.

     Header Block contents:

     All word and double-word values are byte-reversed.

     Offset  Length  Content
     ------  ------  ---------------------------------------------------------------
     +0      1       $4E - Header ID Byte #1
     +1      1       $F5 - Header ID Byte #2  Spells "NuFX" in alternating ascii
     +2      1       $46 - Header ID Byte #3  (high/low) for uniqueness.
     +3      1       $D8 - Header ID Byte #4

     +4      2       header_crc

                     16-bit CRC of the remaining fields of this block.
                     (bytes 6 through the end of the attributes, filename, and
                      any threads.)

                     This field is used to verify the integrity of the rest of the
                     block.

                     Programs which make NuFX archives *MUST* include this
                     in every header.  It is up to the discretion of the extracting
                     program to check the validity of these bytes.  Any programs
                     which might modify the header of a particular record *MUST*
                     recalculate the CRC for the header block.

     +6      2       attrib_count

                     This field describes the length of the attribute section of each
                     header in bytes.  This count measures the distance in bytes
                     from the first field (offset +0) to and including the
                     filename_length field.  By convention, the filename_length
                     field will always be the last 2 bytes of the attribute
                     section regardless of what has preceded it.

     NuFX Documentation  2/3/89                             - Page 9 -

     +8      2       version_number

                     Minimum NuFX version number needed for extraction.
                     (Currently $0000)

                     This field is used to detect the possible existence of
                     other as-of-yet undefined fields and features.  Utility
                     programs should check this value to be certain that they
                     are capable of extracting a record with this minimum version.

     +10     4       total_threads

                     The number of thread sub-records which should be expected
                     immediately following the end of the file/path name.  This
                     field is extremely important because it contains the
                     information about the length of the last 1/3 of the header.

     +14     2       file_sys_id

                     Native file system identifier:

                     $0000   reserved
                     $0001   ProDOS/SOS
                     $0002   DOS 3.3
                     $0003   DOS 3.2
                     $0004   Apple II Pascal
                     $0005   Macintosh(tm) (HFS)
                     $0006   Macintosh (MFS)
                     $0007   LISA(tm) file system
                     $0008   Apple CP/M
                     $0009   reserved, do not use
                     $000A   MS-DOS
                     $000B   High-Sierra/ISO 9660

                     $000C
                     .
                     .       reserved
                     .
                     $FFFF

                     Disk: if the file system of a disk is not known, then
                      this field should be set to null (0000).

     NuFX Documentation  2/3/89                            - Page 10 -

     +16     2       file_sys_info

                     Information about the current filing system:

                     [$00xx]

                     Native file system separator.  Under Prodos, the "/" ($2F)
                     character is used to separate paths.  Under HFS, the
                     ":" ($3A) character is used to separate paths.  Under
                     MS-DOS, the "\" ($5C) character is used to separate paths.
                     The low byte of this word is used to store the file system's
                     separator.

                     The primary reason for including this field is that the
                     receiving file system (say, to Prodos 8 from GS/OS running an
                     HFS File System Translator) must know how to parse a valid
                     file/path name from the filename field for the receiving file
                     system.

                     [$xx00]

                     Sparse byte.  If the high-byte of this word is $01, then
                     the image which follows is a sparse file (and the threads
                     should have been filled in properly to indicate this).  If
                     a more "normal" image follows, this byte will be null (00).

     NuFX Documentation  2/3/89                            - Page 11 -

     +18     4       access          [0000 0000 0000 0000 DRB00IWR]

                     bits 31-8       reserved, must be zero
                     bit 7           D=0, destroy disabled
                                     D=1, destroy enabled
                     bit 6           R=0, rename disabled
                                     R=1, rename enabled
                     bit 5           B=0, backup not needed
                                     B=1, backup needed
                     bits 4-3        reserved, must be zero
                     bit 2           I=0, file is visible
                                     I=1, file is invisible
                     bit 1           W=0, write disabled
                                     W=1, write enabled
                     bit 0           R=0, read disabled
                                     R=1, read enabled

                     Disk: this field should be set to null (00).

     +22     4       file_type

                     Disk: this field should be set to null (00).

     +26     4       extra_type

                     ProDOS aux_type or HFS creator_type

                     Disk: this field *MUST* be set to the total number of blocks
                       on the device.  This information must be present so that
                       the extracting program can place the record on the proper
                       type of device.

     +30     2       storage_type

                     $0 - $3 = standard file
                     $5      = extended (gs/os) file
                     $d      = subdirectory

              Disk:  file_sys_block_size

                     This should only be used if a disk is being archived. The block
                     size used by the device should be placed in this field.  For
                     example, under Prodos, this field will be 512, while HFS
                     would set it to 524.

     NuFX Documentation  2/3/89                            - Page 12 -

     +32     8       create_when

                     The date and time on which this record was initially created.
                     If the creation date and time is available from a disk device,
                     this information should be included.

                     The format of this field is as follows:

                     +32     second - 0 through 59
                     +33     minute - 0 through 59
                     +34     hour - 0 through 23
                     +35     current Year minus 1900
                     +36     day - 0 through 30
                     +37     month - 0 through 11, with 0=January
                     +38     filler byte - reserved, must be set to null (00).
                     +39     weekDay - 1 through 7, with 1=Sunday

                     The format of this field is identical to that described
                     in the _ReadTimeHex ($0D03) call described on page 14-14
                     of the Apple_IIgs_Toolbox_Reference:_Volume_1.

                     If the date is not known, or is unable to be calculated, this
                     field should be set to null (00).  If the weekDay is not
                     known, or is unable to be calculated, this field should be
                     set to null (00).

     +40     8       mod_when

                     The date and time on which this record was last modified.
                     If the modification date is available from a disk device,
                     this information should be included.

                     The format of this field is as follows:

                     +40     second - 0 through 59
                     +41     minute - 0 through 59
                     +42     hour - 0 through 23
                     +43     current Year minus 1900
                     +44     day - 0 through 30
                     +45     month - 0 through 11, with 0=January
                     +46     filler byte - reserved, must be set to null (00).
                     +47     weekDay - 1 through 7, with 1=Sunday

                     The format of this field is identical to that described
                     in the _ReadTimeHex ($0D03) call described on page 14-14
                     of the Apple_IIgs_Toolbox_Reference:_Volume_1.

                     If the date is not known, or is unable to be calculated, this
                     field should be set to null (00).  If the weekDay is not
                     known, or is unable to be calculated, this field should be
                     set to null (00).

     NuFX Documentation  2/3/89                            - Page 13 -

     +48     8       archive_when

                     The date and time on which this record was placed in this
                     archive.

                     The format of this field is as follows:

                     +48     second - 0 through 59
                     +49     minute - 0 through 59
                     +50     hour - 0 through 23
                     +51     current Year minus 1900
                     +52     day - 0 through 30
                     +53     month - 0 through 11, with 0=January
                     +54     filler byte - reserved, must be set to null (00).
                     +55     weekDay - 1 through 7, with 1=Sunday

                     The format of this field is identical to that described
                     in the _ReadTimeHex ($0D03) call described on page 14-14
                     of the Apple_IIgs_Toolbox_Reference:_Volume_1.

                     If the date is not known, or is unable to be calculated, this
                     field should be set to null (00).  If the weekDay is not
                     known, or is unable to be calculated, this field should be
                     set to null (00).

     Any other attributes which are needed may be added at the discretion of the
     NuFX application programmer.  The attrib_count field should be modified
     accordingly.

     NuFX Documentation  2/3/89                            - Page 14 -

     attrib_count-2  filename_length (xx bytes)

                     Length of filename.  Under Prodos, this will not exceed 64
                     characters.  If HFS or another filing system is used, this
                     field may exceed 64 characters.  This is the last field
                     considered included in the attributes section.  To allow the
                     inclusion of future additional parameters in the attributes
                     section,  NuFX utility programs should rely on the
                     attribs_count field to find the filename_length field.

     -------------------------
     End of attributes section

          xx Bytes   Filename or partial pathname if applicable.

                     If this is a disk which is being archived, then the
                     volume_name should be included in this field.  If a volume
                     name is included in this field, a separator ("/" or ":")
                     should *NOT* be included in, or precede the name.  If a volume
                     name is not available, then this field should be set to nulls.
                     (00's)

                     If a partial pathname is specified, the directories to which
                     the current pathname refers need not have preceded this
                     particular record.  The extraction program must test each
                     referenced directory individually.  If the directory in
                     question does not exist, the extracting program should create
                     it.

                     Any utility which extracts files from a NuFX archive *MUST NOT*
                     assume that this field will be in a format it is able to
                     handle.  In particular, extraction programs should check for
                     mixed case text in a file/path name and do whatever
                     conversions are necessary to parse a legal file/path name.
                     In general, assume nothing.

     -----------------------
     End of filename section

     NuFX Documentation  2/3/89                            - Page 15 -

     Threads
     -------

     Thread records are 16 byte records which immediately follow the filename and
     describe the types of data structures which are included with a given record.
     The number of thread records is described in the attribute section by a
     longword, total_threads.

     Each thread record should be checked for the type of information that a given
     utility program can extract.  If a utility is incapable of extracting a
     particular thread, that thread should be skipped.  If a utility finds a
     redundancy in a thread_record, it must decide whether to skip the record or to
     do something with that particular thread (ie, if a utility finds 2
     message_threads it can either ignore the second thread or display it. Likewise,
     if a utility finds 2 resource threads, it can either overwrite the first thread
     which was extracted, or warn the user and skip the errant thread).

     A thread record can be represented as follows:

     Offset  Length  Content
     ------  ------  ---------------------------------------------------------------
     +0      2       thread_class
     +2      2       thread_format
     +4      2       thread_kind
     +6      2       reserved
     +8      4       thread_eof
     +12     4       comp_thread_eof

     "thread_class" describes the classification of the thread
     ---------------------------------------------------------

     $0000   =       message_thread
     $0001   =       control_thread
     $0002   =       data_thread
     $0003   =       sparse_thread

     NuFX Documentation  2/3/89                            - Page 16 -

     "thread_format" is the format of the data within the thread.
     ------------------------------------------------------------

     $0000   =       Uncompressed                    [Not application specific]
     $0001   =       SQueezed (SQ/USQ)               [Not application specific]

     $0002   =       Dynamic LZW                     [ShrinkIt]

     $0003
      .
      .      RESERVED, contact the author
      .

     $FFFF

     "thread_kind" describes the kind of data which is contained in the thread
     -------------------------------------------------------------------------

     if thread_class
        $0000   =       message_thread
                        thread_kind $0000 = ASCII text
                                    $xxxx = all others undefined

        $0001   =       control_thread
                        thread_kind $0000 = create directory
                                    $xxxx = all others undefined

        $0002   =       data_thread
                        thread_kind $0000 = data_fork of file
                        thread_kind $0001 = disk image
                        thread_kind $0002 = resource_fork of file
                                    $xxxx = all others undefined

     "thread_eof" is the length of the uncompressed thread
     -----------------------------------------------------

     "comp_thread_eof" is the length of the compressed thread
     --------------------------------------------------------

     Current ideas for messages include static pictures, sounds, sound & pictures,
     animations, and possibly executable files.  I encourage writers of NuFX
     utility programs to be able to handle messages of the lowest common
     denominator, ASCII text.

     NuFX Documentation  2/3/89                            - Page 17 -

     Finding the start of the thread list
     ------------------------------------

     The beginning of the thread records can be found by using the following
     algorithm:

     Threads := (mark at beginning of header) + (attrib_count) +
                 (filename_length)

     Finding the end of the thread list
     ----------------------------------

     The end of the thread records can be found by applying the following
     algorithm:

     endOfThreads := (mark at beginning of header) + (attrib_count) +
                      (filename_length) + (16 * total_threads)

     Finding the start of a data_thread
     ----------------------------------

     The beginning of a data_thread can be found using the following algorithm:

     Data Mark := (mark at beginning of header) + (attrib_count) +
                    (filename_length) + (16 * total_threads) +
                      (comp_thread_eof of all threads in the thread list which
                       are not data prior to finding a data_thread)

     Finding the start of a resource_thread
     --------------------------------------

     The beginning of a resource_thread can be found using the following algorithm:

     Resource Mark := (mark at beginning of header) + (attrib_count) +
                        (filename_length) + (16 * total_threads) +
                          (comp_thread_eof of all the threads in the thread list
                           which are not resources prior to finding a
                           resource_thread)

     Finding the next record
     -----------------------

     The next record can be found using the following algorithm:

     Next Mark := (mark at beginning of header) + (attrib_count) +
                   (filename_length) + (16 * total_threads) +
                    (comp_thread_eof of each thread)

     NuFX Documentation  2/3/89                            - Page 18 -

     Misc notes on threads
     ---------------------

     There must *ALWAYS* be at least 1 thread attached to each record, whether
     the thread has any physical length or not.  Phantom files and directories will
     have both the thread_eof and comp_thread_eof fields set to null (00).

     If a control_thread indicates that a directory should be created on the
     destination device, the path to be created must take the form of a prodos
     partial pathname.  That is, the path must *NOT* be preceded with a volume
     name.  ie, /STUFF/SUBDIR is an invalid path, while SUBDIR/ANOTHERSUB is
     a legal path.

     If a control_thread indicates that a directory is to be created, *ALL*
     the subdirectories that are contained in the pathname must be created.

     Control_threads will be eventually used to control the execution of utility
     programs by allowing for directory creation, renaming, deleting, moving,
     or modifying files.  A form of scripting language will eventually be available
     to allow utility programs to perform these actions automatically.
     Control_threads will allow extraction programs to perform operations akin to
     Apple's GS/OS installer program, allowing updates to program sets dependent
     upon such things as date of creation or modification, version number, etc.

     NuFX Documentation  2/3/89                            - Page 19 -

     Normal Files
     ------------

     Normal Prodos files (sub_types $01,$02,$03) should be handled in the
     following manner: the data portion of the file will occupy the first
     data_thread.

     Sample header block for a normal file record:

           00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
         +-------------------------------------------------+  created 01:10:00
      00 | 4E F5 46 D8 55 34 3A 00 00 00 01 00 00 00 01 00 |          10/22/88
      10 | 2f 00 00 00 c3 00 04 00 00 00 00 00 00 00 01 00 |          saturday
      20 | 00 0a 01 58 16 0a 00 07 00 10 0b 58 11 0b 00 05 |
      30 | 00 0c 01 28 16 0a 00 07 05 00 53 54 55 46 46 02 | last mod 11:16:00
      40 | 00 02 00 00 00 00 00 00 20 00 00 00 10 00 00    |          11/17/88
         +-------------------------------------------------+          thursday

                                                             archived 01:12:00
         header_id             = "NuFX"                               10/22/88
         header_crc            = $3455                                saturday
         attrib_count          = $003A (58 bytes in attrib section)
         version               = $0000
         total_threads         = $00000001
         file_sys_id           = $0001 (Prodos)
         file_sys_info         = $002f (not sparse, / = separator)
         access                = $000000C3 (full access, not invis)
         filetype              = $00000004 (Prodos BIN)
         aux_type              = $00000000
         storage_type          = $0001 (Prodos sapling file)
         create_when           = 00 0a 01 58 16 0a 00 07
         mod_when              = 00 10 0b 58 11 0b 00 05
         archive_when          = 00 0c 01 58 16 0a 00 07

         filename_length       = $0005
         filename              = "STUFF"

         thread_class          = $0002 (data_thread)
         thread_format         = $0002 (compressed with ShrinkIt)
         thread_kind           = $0000 (file)
         reserved              = $0000
         thread_eof            = $00002000
         comp_thread_eof       = $00001000 (file is 50% of original size)

     NuFX Documentation  2/3/89                            - Page 20 -

     Extended Files
     --------------

     Sample header block for an extended file record:

           00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
         +-------------------------------------------------+  created 01:10:00
      00 | 4E F5 46 D8 65 78 3A 00 00 00 02 00 00 00 01 00 |          10/22/88
      10 | 2f 00 00 00 c3 00 b3 00 00 00 00 00 00 00 05 00 |          saturday
      20 | 00 0a 01 58 16 0a 00 07 00 10 0b 58 11 0b 00 05 |
      30 | 00 0c 01 58 16 0a 00 07 09 00 45 58 54 2e 53 54 | last mod 11:16:00
      40 | 55 46 46 02 00 02 00 00 00 00 00 00 20 00 00 00 |          11/17/88
      50 | 08 00 00 02 00 02 00 00 00 00 00 00 10 00 00 00 |          thursday
      60 | 08 00 00                                        |
         +-------------------------------------------------+ archived 01:12:00
                                                                      10/22/88
         header_id             = "NuFX"                               saturday
         header_crc            = $7865
         attrib_count          = $003A (58 bytes in attrib section)
         version               = $0000
         total_threads         = $00000002
         file_sys_id           = $0001 (Prodos)
         file_sys_info         = $002f (not sparse, / = separator)
         access                = $000000C3 (full access, not invis)
         filetype              = $000000B3 (Prodos S16)
         aux_type              = $00000000
         storage_type          = $0005 (extended file)
         create_when           = 00 0a 01 58 16 0a 00 07
         mod_when              = 00 10 0b 58 11 0b 00 05
         archive_when          = 00 0c 01 58 16 0a 00 07

         filename_length       = $0009
         filename              = "EXT.STUFF"

         thread_class          = $0002 (data_thread)
         thread_format         = $0002 (compressed by ShrinkIt)
         thread_kind           = $0000 (file)
         reserved              = $0000
         thread_length         = $00002000
         comp_thread_length    = $00000800 (data_fork is 25% of original size)

         thread_class          = $0002 (data_thread)
         thread_format         = $0002 (compressed by ShrinkIt)
         thread_kind           = $0002 (resource_fork)
         reserved              = $0000
         thread_eof            = $00001000
         comp_thread_eof       = $00000800 (resource is 50% of original size)

     NuFX Documentation  2/3/89                            - Page 21 -

     Disks
     -----

     If the file system of a particular disk is not known, the file_sys_id field
     should be set to null, the volume name should also be set to null, and all
     the other fields pertaining only to files should be set to null.

     If the file system of a particular disk *IS* known, as many of the fields
     as possible should be filled with the correct information.  Fields which do not
     pertain to an archived disk should remain set to null.

     If an entire disk is added to the archive without some form of compression
     (ie, record_format = uncompressed), then the blocks which comprise the disk
     image *MUST* be added sequentially from the first through the last block.
     Since there will be no character included in the data stream to mark the
     end/beginning of a block, extraction programs should rely on the
     file_sys_block_size field to determine how many bytes to read from the record
     to properly fill a block.

     NuFX Documentation  2/3/89                            - Page 22 -

     Sample header block for a disk record:

           00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
         +-------------------------------------------------+  created 01:10:00
      00 | 4E F5 46 D8 67 05 3A 00 00 00 01 00 00 00 01 00 |          10/22/88
      10 | 2f 00 00 00 00 00 00 00 00 00 40 06 00 00 00 02 |          saturday
      20 | 00 0a 01 58 16 0a 00 07 00 10 0b 58 11 0b 00 05 |
      30 | 00 0c 01 58 16 0a 00 07 04 00 44 49 53 4B 02 00 | last mod 11:16:00
      40 | 02 00 01 00 00 00 00 00 00 00 51 45 07 00       |          11/17/88
         +-------------------------------------------------+          thursday

                                                             archived 01:12:00
         header_id             = "NuFX"                               10/22/88
         header_crc            = $0567                                saturday
         attrib_count          = $003A (58 bytes in attrib section)
         version               = $0000
         total_threads         = $00000001 (one thread)
         file_sys_id           = $0001 (Prodos)
         file_sys_info         = $002f (not sparse, / = separator)
         access                = $00000000 (none)
         filetype              = $00000000 (none)
         aux_type/creator_type = $00000640 (1600 blocks on device -- 3.5" disk)
         storage_type          = $0200 (block size = 512 bytes)
         create_when           = 00 0a 01 58 16 0a 00 07
         mod_when              = 00 10 0b 58 11 0b 00 05
         archive_when          = 00 0c 01 58 16 0a 00 07

         filename_length       = $0004
         filename              = "DISK"

         thread_class          = $0002 (data_thread)
         thread_format         = $0002 (compressed with ShrinkIt)
         thread_kind           = $0001 (disk image)
         reserved              = $0000
         thread_eof            = $00000000 (unknown size before compressing)
         comp_thread_eof       = $00074551 (size after compression)

     NuFX Documentation  2/3/89                            - Page 23 -

     Directories
     -----------

     Directories are handled almost the same way that normal files are handled with
     the exception that there will be no data in the thread which follows the entry.
     A thread_record *MUST* exist to inform a utility that a directory is to be
     created through the use of the proper control_thread value.

     Directories do not necessarily have to precede a record which references a
     directory.  ie, if a record contains STUFF/MY.STUFF, the directory "STUFF"
     need not exist for the extracting program to properly extract the record.  The
     extracting program must check to see if each of the directories referenced
     exist, and if they do not exist, create them.  While this method places a great
     burden on the abilities of the extraction program, it avoids the anomalies
     associated with the deletion of directories within an archive.

     NuFX Documentation  2/3/89                            - Page 24 -

     Cyclic Redundancy Checks (CRC's)
     --------------------------------

     Many people are not aware of how to calculate a CRC, so to provide this
     function, I am providing source code to a very fast routine which does the crc
     calculation.  The routine "makeLookup" needs to be called only once.  After
     this, the routine "doByte" should be called repeatedly with each new byte in
     succession to generate the cumulative CRC for the block.  The CRC word should
     be reset to null (0000) before beginning each new CRC.

     This is the same CRC calculation which is done for CRC/Xmodem, and Ymodem.  The
     code is easily portable to a 16-bit environment like the Apple IIgs.  The only
     detrimental factor with this routine is that it requires 512 bytes of main
     memory to operate.  If you can spare the space, this is one of the fastest
     routines I know to generate a CRC-16 on a 6502-type machine.

     *-------------------------------
     * fast crc routine based on table lookups by
     * Andy Nicholas - 03/30/88 - merlin 'c02 - easily portable to nmos 6502 also.
     * easily portable into orca/m format, just snip and save.

              xc                             turn 65c02 opcodes on

     *-------------------------------
     * routine to make the lookup tables
     *-------------------------------

     makeLookup
              LDX   #0                       zero first page
     zeroLoop STZ   crclo,x                  zero crc lo bytes
              STZ   crchi,x                  zero crc hi bytes
              INX
              BNE   zeroLoop

     *-------------------------------
     * the following is the normal bitwise computation
     * tweeked a little to work in the table-maker

     docrc
              LDX   #0                       number to do crc for

     fetch    TXA
              EOR   crchi,x                  add byte into high
              STA   crchi,x                  of crc

              LDY   #8                       do 8 bits
     loop     ASL   crclo,x                  shift current crc-16 left
              ROL   crchi,x
              BCC   loop1

     NuFX Documentation  2/3/89                            - Page 25 -

     * if previous high bit wasn't set, then don't add crc
     * polynomial ($1021) into the cumulative crc.  else add it.

              LDA   crchi,x                  add hi part of crc poly into
              EOR   #$10                     cumulative crc hi
              STA   crchi,x

              LDA   crclo,x                  add lo part of crc poly into
              EOR   #$21                     cumulative crc lo
              STA   crclo,x
     loop1    DEY                            do next bit
              BNE   loop                     done? nope, loop

              INX                            do next number in series (0-255)
              BNE   fetch                    didn't roll over, so fetch more
              RTS                            done

     crclo    ds    256                      space for low byte of crc table
     crchi    ds    256                      space for high bytes of crc table

     *-------------------------------
     * do a crc on 1 byte/fast
     * on initial entry, CRC should be initialized to 0000
     * on entry, A = byte to be included in CRC
     * on exit, CRC = new CRC
     *-------------------------------

     doByte
              EOR   crc+1                    add byte into crc hi byte
              TAX                            to make offset into tables

              LDA   crc                      get previous lo byte back
              EOR   crchi,x                  add it to the proper table entry
              STA   crc+1                    save it

              LDA   crclo,x                  get new lo byte
              STA   crc                      save it back

              RTS                            all done

     crc      dw    0000                     cumulative crc for all data

     NuFX Documentation  2/3/89                            - Page 26 -

     Possible Block Combinations
     ---------------------------

     The blocks *MUST* occur in the following fashion:

             Master Header block containing N entries

             Header block
             threads (message, control, data, or resource)

             .
             .
             .

             Next Header block (notice no second Master Header block)
             threads (message, control, data, or resource)

             .
             .
             .

             Nth Header Block
             threads (message, control, data, or resource)

     NuFX Documentation  2/3/89                            - Page 27 -

     Known NuFX utility programs:
     ---------------------------

     Name           Author          Description                          Current Ver
     -------------  --------------  ------------------------------------ -----------
     ShrinkIt       Andy Nicholas   Compresses files/disks, provides        0.95
                                     archive and file utilities.
     NuList         Andy Nicholas   Lists contents of NuFX files for        1.1
                                     the GBBS "Pro" (tm) BBS, online.

     NuFX Documentation  2/3/89                            - Page 28 -

     Legal Stuff
     -----------

     Apple, Apple IIGS, AppleLink, GS/OS, Macintosh, and Lisa are registered
      trademarks of Apple Computer, Inc.

     GBBS "Pro" is a registered trademark of L&L Productions.

     About the Author
     ----------------

     I am currently a Junior attending Moravian College in Bethlehem, Pennsylvania,
     majoring in Computer Science.

     Any comments or suggestions you have about NuFX are more than welcome, or if
     you wish to request that any of the fields be assigned your own value, or if
     you would like to inform me of a NuFX utility you have written, you can contact
     me at:

             Paper Bag Productions
             c/o Andy Nicholas
             Box 435
             Moravian College
             Bethlehem, PA  18018

             CSNET       :  nicholaA@moravian.edu
             InterNET    :  nicholaA%batman.moravian.edu@relay.cs.net
                            nicholaA@batman.moravian.edu.csnet
             ProLine     :  andyn@pro-sol.cts.com      [619-670-5379]
             AppleLink PE:  ShrinkIt

     I would like to thank the following people for their help and input during the
     design phase of the NuFX proposal:

     Jason Blochowiak, Morgan Davis, Don Elton, Dave Lyons, Jon Davidson,
     Vince Cooper, Lance Taylor-Warren, Floyd Zink, Kent Dickey, John Brooks,
     Doug Brandon, Todd South, Larry Hawkins, Kevin Keller