Update upstream source from tag 'upstream/2.23'

[debian/cpmtools] / cpm.5.in

diff --git a/cpm.5.in b/cpm.5.in
index 5295621902befeb03b4fc7533f777baf954495d2..5c642e6b9dd998ae1778177bddb78382307908e0 100644 (file)
--- a/cpm.5.in
+++ b/cpm.5.in
@@ -32,7 +32,9 @@ A block is the smallest allocatable storage unit.  CP/M supports block
 sizes of 1024, 2048, 4096, 8192 and 16384 bytes.  Unfortunately, this
 format specification is not stored on the disk and there are lots of
 formats.  Accessing a block is performed by accessing its sectors, which
-are stored with the given software skew.
+are stored with the given software skew.  \fBcpmtools\fP always counts
+sectors starting with 0, as it deals with logical sectors.  CP/M uses physical
+sectors in the skew table, which often start with 1.
 .\"}}}
 .SS "Device areas" \"{{{
 A CP/M disk contains four areas:
@@ -64,6 +66,16 @@ convenience upper and lower case are both accepted and only the first
 letter is significant, thus 2KB, 8MB, 1000trk and 16sec are valid
 values.  The \fBoffset\fP must appear subsequent to track, sector and sector
 length values for the sector and track units to work.
+.LP
+Note that it is possible to reserve space between the directory and
+the beginning of data.  Although typically data follows the directory,
+some systems used this to store extra data instead of using more
+system tracks (see the fields \fBALV0\fP and \fBALV1\fP in the
+DPB).
+.LP
+There are disk formats that map multiple logical tracks onto a physical
+track, which allows a little bit more capacity in case the system image
+size does not match the physical track capacity well.
 .\"}}}
 .SS "Directory entries" \"{{{
 The directory is a sequence of directory entries (also called extents),
@@ -80,9 +92,10 @@ Al   Al      Al      Al      Al      Al      Al      Al      Al      Al      Al      Al      Al      Al      Al      Al
 \fBSt\fP is the status; possible values are:
 .RS
 .sp
-0\*(en15: used for file, status is the user number
+0\*(en15: used for file, status is the user number.  CP/M 2.2 only documents
+0\*(en15 and CCP and PIP only offer those, but the BDOS allows to use 0\*(en31.
 .br
-16\*(en31: used for file, status is the user number (P2DOS)
+16\*(en31: used for file, status is the user number (P2DOS, CP/M 2.2)
 or used for password extent (CP/M 3 or higher)
 .br
 32: disc label
@@ -149,11 +162,13 @@ Rc stores the number of 128 byte records of the last used logical extent.
 Bc stores the number of bytes in the last used record.  The value 0 means
 128 for backward compatibility with CP/M 2.2, which did not support Bc.
 ISX records the number of unused instead of used bytes in Bc.
+This only applies to files with allocated blocks.  For an empty file, no
+block is allocated and Bc 0 has no meaning.
 .\"}}}
 .LP
 .\"{{{ Al     = allocated blocks
 \fBAl\fP stores block pointers.  If the disk capacity minus boot
-tracks but including the directory area is less than 256 blocks, Al
+tracks but including the directory area is less than or equal to 256 blocks, Al
 is interpreted as 16 byte-values, otherwise as 8 double-byte-values.
 Since the directory area is not subtracted, the directory area starts
 with block 0 and files can never allocate block 0, which is why this