mirror of https://github.com/fadden/nulib2.git
Documentation updates for 2.3.0
Various changes including: - Annotation of UTF-8 vs. Mac OS Roman character sets - Change to integers with width specifiers in API Also, constructed a 2IMG file type note from an old a2central page captured by archive.org.
This commit is contained in:
Andy McFadden
parent
f9a6a75c79
commit
7e06de8c66
|
|
@ -0,0 +1,70 @@
|
|||
Universal Disk Image file
|
||||
=========================
|
||||
|
||||
- File Type: $E0
|
||||
- Auxiliary Type: $0130
|
||||
- Full Name: Universal Disk Image file
|
||||
- Short Name: 2IMG
|
||||
- Written by: Eric Shepherd, March 1999
|
||||
|
||||
Files of this type and auxiliary type contain Universal Disk Image format disk images.
|
||||
|
||||
---
|
||||
|
||||
Files of this type and auxtype contain data in Universal Disk Image format. This file format, a recent standard developed by cooperation among Apple II emulator authors, is used to represent an entire Apple II-compatible disk in a data file. It's an extremely easy-to-use and flexible format that's compatible with most currently-supported Apple II emulation products.
|
||||
|
||||
Univeral Disk Image files (also known as '2IMG' or '2MG', from the Macintosh® creator code and filename extensions typically used for these files) consist of four chunks: the header, the data chunk, the comment, and the creator-specific data chunk.
|
||||
|
||||
### The Universal Disk Image header ###
|
||||
|
||||
The header can be described using the following C structure. All values are little-endian (Apple II byte ordering):
|
||||
|
||||
offset | size | description
|
||||
------ | ---- | -----------
|
||||
+$000 | Long | The integer constant '2IMG'. This integer should be little-endian, so on the Apple IIgs, this is equivalent to the four characters 'GMI2'; in ORCA/C 2.1, you can use the integer constant '2IMG'.
|
||||
+$004 | Long | A four-character tag identifying the application that created the file.
|
||||
+$008 | Word | The length of this header, in bytes. Should be 52.
|
||||
+$00A | Word | The version number of the image file format. Should be 1.
|
||||
+$00C | Long | The image format. See table below.
|
||||
+$010 | Long | Flags. See table below.
|
||||
+$014 | Long | The number of 512-byte blocks in the disk image. This value should be zero unless the image format is 1 (ProDOS order).
|
||||
+$018 | Long | Offset to the first byte of the first block of the disk in the image file, from the beginning of the file. The disk data must come before the comment and creator-specific chunks.
|
||||
+$01C | Long | Length of the disk data in bytes. This should be the number of blocks * 512.
|
||||
+$020 | Long | Offset to the first byte of the image comment. Can be zero if there's no comment. The comment must come after the data chunk, but before the creator-specific chunk. The comment, if it exists, should be raw text; no length byte or C-style null terminator byte is required (that's what the next field is for).
|
||||
+$024 | Long | Length of the comment chunk. Zero if there's no comment.
|
||||
+$028 | Long | Offset to the first byte of the creator-specific data chunk, or zero if there is none.
|
||||
+$02C | Long | Length of the creator-specific chunk; zero if there is no creator-specific data.
|
||||
+$030 | 16 bytes | Reserved space; this pads the header to 64 bytes. These values must all be zero.
|
||||
|
||||
|
||||
### Creator Codes ###
|
||||
|
||||
If the file is created by a Macintosh application, this should be the creator code of the creating application; otherwise, this should be a unique ID specific to the creating application. As a courtesy, you should let A2Pro know the creator code you choose to use for your application.
|
||||
|
||||
The following creator codes are already in use by various applications:
|
||||
|
||||
- Bernie ][ the Rescue 'B2TR'
|
||||
- Catakig 'CTKG'
|
||||
- Sheppy's ImageMaker 'ShIm'
|
||||
- Sweet 16 'WOOF'
|
||||
|
||||
|
||||
### The Image Format field ###
|
||||
|
||||
The image format is indicated as one of the following values:
|
||||
|
||||
- DOS 3.3 Order 0
|
||||
- ProDOS Order 1
|
||||
- Nibblized data 2
|
||||
|
||||
|
||||
### The Flags field ###
|
||||
|
||||
The flags field contains bit flags that specify details about the disk image. Bits not defined here must be zero.
|
||||
|
||||
Bit | Description
|
||||
--- | -----------
|
||||
31 | If this bit is set, the disk image is locked and no changes should be permitted to the disk data it contains. This is used by emulators to provide support for write-protecting disk images.
|
||||
8 | If this bit is set, the low byte of the flags field contains the DOS 3.3 volume number of the disk image. This bit should only be set for DOS 3.3 disk images. If the disk is DOS 3.3 format (the image format is 0), and this bit is 0, volume number 254 is assumed.
|
||||
7-0 | The DOS 3.3 volume number, from 0-254, if bit 8 is set. Otherwise these bits should be 0.
|
||||
|
||||
|
|
@ -19,7 +19,8 @@
|
|||
|
||||
<h6> </h6>
|
||||
|
||||
<h6>NuFX Addendum - <b>By Andy McFadden - Last revised 2004/09/26</b></h6>
|
||||
<h6>NuFX Addendum - <b>By Andy McFadden - Last revised 2014/12/22</b></h6>
|
||||
|
||||
<p align="left">This addendum clarifies and extends certain aspects of the <a href="FTN.e08002.htm"> NuFX
|
||||
specification</a>. This was developed by Andy McFadden, and is not an
|
||||
"official" modification of the original document.</p>
|
||||
|
|
@ -158,8 +159,9 @@ strip any leading path components from disk image "storage names".&nbs
|
|||
character in a disk volume name.)<p align="left"><b>Extracting:</b>
|
||||
Applications extracting directly to a disk must strip leading path components
|
||||
before assigning the ProDOS volume name. Applications extracting images to
|
||||
a file don't need to do anything unusual.<p align="left"> <h3 align="left">Filename
|
||||
case sensitivity</h3>
|
||||
a file don't need to do anything unusual.
|
||||
|
||||
<p align="left"> <h3 align="left">Filename case sensitivity</h3>
|
||||
<p align="left">There isn't a "filename is case-sensitive" flag in
|
||||
NuFX archives. Since it was designed primarily for ProDOS and HFS
|
||||
filesystems, neither of which is case-sensitive, we should assume that case is
|
||||
|
|
@ -170,7 +172,17 @@ to display archive contents as a hierarchical tree.<p align="left">Applications
|
|||
should try to recognize that "foo/bar", "foo/BAR", and
|
||||
"FOO/bar" are the same file, but it's probably not worth
|
||||
"probing" a case-sensitive filesystem like Linux ext2 to guarantee
|
||||
such.<p align="left"> <h3 align="left">Duplicate filenames</h3>
|
||||
such.
|
||||
|
||||
<p align="left"> <h3 align="left">Filename character set</h3>
|
||||
<p align="left">GS/OS and contemporary Macintoshes used the
|
||||
<a href="http://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/ROMAN.TXT">Mac OS Roman</a>
|
||||
character set. Since GS/ShrinkIt was designed to handle ProDOS and HFS
|
||||
filenames, it's reasonable to declare that all filenames should be interpreted
|
||||
as Mac OS Roman. Applications should convert filenames to and from the
|
||||
Unicode equivalents when extracting and adding files.
|
||||
|
||||
<p align="left"> <h3 align="left">Duplicate filenames</h3>
|
||||
<p align="left">There is nothing in the NuFX specification that prevents having
|
||||
more than one file with the same name in an archive. In practice, this is
|
||||
inconvenient, especially for users with command-line tools. On the other
|
||||
|
|
@ -530,7 +542,7 @@ also accept the year 0. However, if you find a Date/Time with zero in all
|
|||
useful fields (second, minute, hour, day, month, year), treat it as an
|
||||
unspecified date rather than midnight of January 1, 2000.</p>
|
||||
<hr>
|
||||
<p>This document is Copyright © 2000-2004 by <a href="http://www.fadden.com/">Andy
|
||||
<p>This document is Copyright © 2000-2004 by <a href="http://www.fadden.com/">Andy
|
||||
McFadden</a>. All Rights Reserved.</p>
|
||||
<p>The latest version can be found on the NuLib web site at
|
||||
<a href="http://www.nulib.com/">http://www.nulib.com/</a>.</p>
|
||||
|
|
|
|||
|
|
@ -380,7 +380,7 @@ the comment designator (for "note") because 'c' is a valid hexadecimal
|
|||
digit.
|
||||
</p>
|
||||
<hr>
|
||||
<p>This document is Copyright © 2000-2003 by <a href="http://www.fadden.com/">Andy
|
||||
<p>This document is Copyright © 2000-2003 by <a href="http://www.fadden.com/">Andy
|
||||
McFadden</a>. All Rights Reserved.</p>
|
||||
<p>The latest version can be found on the NuLib web site at
|
||||
<a href="http://www.nulib.com/">http://www.nulib.com/</a>.</p>
|
||||
|
|
|
|||
Loading…
Reference in New Issue