1 .\" Believe it or not, reportedly there are nroffs which do not know \(en
4 .TH CPM 5 "@UPDATED@" "CP/M tools" "File formats"
5 .SH NAME \"{{{roff}}}\"{{{
6 cpm \- CP/M disk and file system format
9 .SS "Characteristic sizes" \"{{{
10 Each CP/M disk format is described by the following specific sizes:
21 Number of directory entries
25 Number of reserved system tracks (optional)
27 Offset to start of volume (optional and not covered by operating system,
28 but disk driver specific)
31 A block is the smallest allocatable storage unit. CP/M supports block
32 sizes of 1024, 2048, 4096, 8192 and 16384 bytes. Unfortunately, this
33 format specification is not stored on the disk and there are lots of
34 formats. Accessing a block is performed by accessing its sectors, which
35 are stored with the given software skew. \fBcpmtools\fP always counts
36 sectors starting with 0, as it deals with logical sectors. CP/M uses physical
37 sectors in the skew table, which often start with 1.
39 .SS "Device areas" \"{{{
40 A CP/M disk contains four areas:
43 Volume offset (optional and not covered by operating system, but disk driver specific)
45 System tracks (optional)
52 The system tracks store the boot loader and CP/M itself. In order to save
53 disk space, there are non-bootable formats which omit those system tracks.
54 The term \fIdisk capacity\fP always excludes the space for system tracks.
55 Note that there is no bitmap or list for free blocks. When accessing a
56 drive for the first time, CP/M builds this bitmap in core from the directory.
58 A hard disk can have the additional notion of a \fIvolume offset\fP to
59 locate the start of the drive image (which may or may not have system
60 tracks associated with it). The base unit for volume offset is byte
61 count from the beginning of the physical disk, but specifiers of
62 \fIK\fP, \fIM\fP, \fIT\fP or \fIS\fP may be appended to denote
63 kilobytes, megabytes, tracks or sectors. If provided, a specifier
64 must immediately follow the numeric value with no whitespace. For
65 convenience upper and lower case are both accepted and only the first
66 letter is significant, thus 2KB, 8MB, 1000trk and 16sec are valid
67 values. The \fBoffset\fP must appear subsequent to track, sector and sector
68 length values for the sector and track units to work.
70 Note that it is possible to reserve space between the directory and
71 the beginning of data. Although typically data follows the directory,
72 some systems used this to store extra data instead of using more
73 system tracks (see the fields \fBALV0\fP and \fBALV1\fP in the
76 There are disk formats that map multiple logical tracks onto a physical
77 track, which allows a little bit more capacity in case the system image
78 size does not match the physical track capacity well.
80 .SS "Directory entries" \"{{{
81 The directory is a sequence of directory entries (also called extents),
82 which contain 32 bytes of the following structure:
85 .ta 3n 6n 9n 12n 15n 18n 21n 24n 27n 30n 33n 36n 39n 42n 45n
86 St F0 F1 F2 F3 F4 F5 F6 F7 E0 E1 E2 Xl Bc Xh Rc
88 Al Al Al Al Al Al Al Al Al Al Al Al Al Al Al Al
92 \fBSt\fP is the status; possible values are:
95 0\*(en15: used for file, status is the user number. CP/M 2.2 only documents
96 0\*(en15 and CCP and PIP only offer those, but the BDOS allows to use 0\*(en31.
98 16\*(en31: used for file, status is the user number (P2DOS, CP/M 2.2)
99 or used for password extent (CP/M 3 or higher)
103 33: time stamp (P2DOS)
110 .\"{{{ F0-E2 = file name and extension
111 \fBF0\*(enE2\fP are the file name and its extension. They may consist of
112 any printable 7 bit ASCII character but: \fB< > . , ; : = ? * [ ]\fP.
113 The file name must not be empty, the extension may be empty. Both are
114 padded with blanks. The highest bit of each character of the file name
115 and extension is used as attribute. The attributes have the following
119 F0: requires set wheel byte (Backgrounder II)
121 F1: public file (P2DOS, ZSDOS), forground-only command (Backgrounder II)
123 F2: date stamp (ZSDOS), background-only commands (Backgrounder II)
125 F7: wheel protect (ZSDOS)
134 Public files (visible under each user number) are not supported by CP/M
135 2.2, but there is a patch and some free CP/M clones support them without
138 The wheel byte is (by default) the memory location at 0x4b. If it is
139 zero, only non-privileged commands may be executed.
142 .\"{{{ Xl, Xh = extent number
143 \fBXl\fP and \fBXh\fP store the extent number. A file may use more than
144 one directory entry, if it contains more blocks than an extent can hold.
145 In this case, more extents are allocated and each of them is numbered
146 sequentially with an extent number. If a physical extent stores more than
147 16k, it is considered to contain multiple logical extents, each pointing
148 to 16k data, and the extent number of the last used logical extent
149 is stored. Note: Some formats decided to always store only one logical
150 extent in a physical extent, thus wasting extent space. CP/M 2.2 allows
151 512 extents per file, CP/M 3 and higher allow up to 2048. Bit 5\*(en7 of
152 Xl are 0, bit 0\*(en4 store the lower bits of the extent number. Bit 6
153 and 7 of Xh are 0, bit 0\*(en5 store the higher bits of the extent number.
156 .\"{{{ Rc, Bc = record count, byte count
157 \fBRc\fP and \fBBc\fP determine the length of the data used by this extent. The
158 physical extent is divided into logical extents, each of them being 16k
159 in size (a physical extent must hold at least one logical extent, e.g. a
160 blocksize of 1024 byte with two-byte block pointers is not allowed).
161 Rc stores the number of 128 byte records of the last used logical extent.
162 Bc stores the number of bytes in the last used record. The value 0 means
163 128 for backward compatibility with CP/M 2.2, which did not support Bc.
164 ISX records the number of unused instead of used bytes in Bc.
165 This only applies to files with allocated blocks. For an empty file, no
166 block is allocated and Bc 0 has no meaning.
169 .\"{{{ Al = allocated blocks
170 \fBAl\fP stores block pointers. If the disk capacity minus boot
171 tracks but including the directory area is less than or equal to 256 blocks, Al
172 is interpreted as 16 byte-values, otherwise as 8 double-byte-values.
173 Since the directory area is not subtracted, the directory area starts
174 with block 0 and files can never allocate block 0, which is why this
175 value can be given a new meaning: A block pointer of 0 marks a hole in
176 the file. If a hole covers the range of a full extent, the extent will
177 not be allocated. In particular, the first extent of a file does not
178 neccessarily have extent number 0. A file may not share blocks with other
179 files, as its blocks would be freed if the other files is erased without
180 a following disk system reset. CP/M returns EOF when it reaches a hole,
181 whereas UNIX returns zero-value bytes, which makes holes invisible.
184 .SS "Native time stamps" \"{{{
185 P2DOS and CP/M Plus support time stamps, which are stored in each fourth
186 directory entry. This entry contains the time stamps for
187 the extents using the previous three directory entries. Note that you
188 really have time stamps for each extent, no matter if it is the first
189 extent of a file or not. The structure of time stamp entries is:
194 8 bytes time stamp for third-last directory entry
198 8 bytes time stamp for second-last directory entry
202 8 bytes time stamp for last directory entry
205 A time stamp consists of two dates: Creation and modification date (the
206 latter being recorded when the file is closed). CP/M Plus further
207 allows optionally to record the access instead of creation date as first
211 2 bytes (little-endian) days starting with 1 at 01-01-1978
213 1 byte hour in BCD format
215 1 byte minute in BCD format
218 All time stamps are stored in local time.
220 .SS "DateStamper time stamps" \"{{{
221 The DateStamper software added functions to the BDOS to manage
222 time stamps by allocating a read only file with the name "!!!TIME&.DAT"
223 in the very first directory entry, covering the very first data
224 blocks. It contains one entry per directory entry with the
225 following structure of 16 bytes:
228 5 bytes create datefield
230 5 bytes access datefield
232 5 bytes modify datefield
234 1 byte magic number/checksum
237 The magic number is used for the first 7 entries of each 128-byte record
238 and contains the characters \fB!\fP, \fB!\fP, \fB!\fP, \fBT\fP, \fBI\fP,
239 \fBM\fP and \fBE\fP. The checksum is used on every 8th entry (last entry
240 in 128-byte record) and is the sum of the first 127 bytes of the record.
241 Each datefield has this structure:
244 1 byte BCD coded year (no century, so it is sane assuming any year < 70
247 1 byte BCD coded month
251 1 byte BCD coded hour or, if the high bit is set, the high byte of a
252 counter for systems without real time clock
254 1 byte BCD coded minute, or the low byte of the counter
258 .SS "Disc labels" \"{{{
259 CP/M Plus support disc labels, which are stored in an arbitrary directory
261 The structure of disc labels is:
266 \fBF0\*(enE2\fP are the disc label
268 1 byte mode: bit 7 activates password protection, bit 6 causes time stamps on
269 access, but 5 causes time stamps on modifications, bit 4 causes time stamps on
270 creation and bit 0 is set when a label exists. Bit 4 and 6 are exclusively set.
272 1 byte password decode byte: To decode the password, xor this byte with the password
273 bytes in reverse order. To encode a password, add its characters to get the
280 4 bytes label creation time stamp
282 4 bytes label modification time stamp
286 .SS "Passwords" \"{{{
287 CP/M Plus supports passwords, which are stored in an arbitrary directory
289 The structure of these entries is:
292 1 byte status (user number plus 16)
294 \fBF0\*(enE2\fP are the file name and its extension.
296 1 byte password mode: bit 7 means password required for reading, bit 6 for writing
297 and bit 5 for deleting.
299 1 byte password decode byte: To decode the password, xor this byte with the password
300 bytes in reverse order. To encode a password, add its characters to get the
projects / debian / cpmtools / blob