Inside a DOS 2 Disk: VTOC, Directory, Sector Links and Deleted Files
Atari DOS 2.0S, DOS 2.5 and their many compatibles (MyDOS for small disks, and others) all store files the same way. Knowing that layout lets you make sense of sector editors, recover a deleted file, understand odd errors such as "file number mismatch" (164), and write programs that read a disk directly. The format is simple: one sector of free-space bitmap, eight sectors of directory, and data sectors chained together by pointers.
What you'll learn: where everything lives on a single-density disk, the byte layout of the VTOC, directory entries and data sectors, the famous off-by-one bug, what deleting a file really does, and a BASIC program that reads the structures directly.
What you need: Atari BASIC, DOS 2.0S or 2.5, and a disk or ATR image you don't mind experimenting on. SIO Explained covers the sector-reading routine used here.
1. The map of a 720-sector disk
| Sectors | Contents |
|---|---|
| 1–3 | Boot sectors: loaded by the OS at power-up; their code then reads DOS.SYS by following its sector chain |
| 4 onwards | DOS.SYS when the disk has DOS on it (DUP.SYS follows as an ordinary file) |
| 360 | VTOC, the volume table of contents |
| 361–368 | Directory: 8 sectors × 8 entries = 64 files at most |
| everything else | File data |
| 720 | Never used by DOS 2 (see section 3) |
Bill Wilkinson's Inside Atari DOS explains why the VTOC and directory sit at 360–368: they are consulted constantly, and the middle of the disk gives the shortest average seek from anywhere else. Each sector holds 128 bytes. Enhanced-density disks under DOS 2.5 have 1,040 sectors, with a second VTOC at sector 1024 for the sectors above 719 (see Atari DOS 2.5: A Practical Guide).
2. Data sectors: 125 bytes and a link
Every data sector carries 125 bytes of data plus three bytes of control information:
| Byte | Contents |
|---|---|
| 0–124 | Data |
| 125 | Bits 7–2: the file number (the file's position in the directory, 0–63). Bits 1–0: high bits of the next sector number |
| 126 | Low 8 bits of the next sector number (10 bits in all, so up to 1023) |
| 127 | Number of data bytes actually used in this sector (0–125) |
A file is a chain: the directory gives the first sector, each sector points to the next, and a link of 0 marks the last sector. The file-number field is a safety check. DOS compares it with the directory position of the file it thinks it is reading. If they differ (because a link points into another file, or a stale NOTE/POINT position is used), it stops with ERROR 164, file number mismatch rather than reading the wrong data.
On a real DOS 2.5 disk we examined, sector 4 (the first sector of DOS.SYS) ended with 0, 5, 125: file number 0, next sector 5, 125 bytes used.
3. The VTOC and the off-by-one bug
| Byte | Contents |
|---|---|
| 0 | DOS code (2 for DOS 2) |
| 1–2 | Total usable sectors (707 on a standard disk) |
| 3–4 | Free sectors |
| 10–99 | Bitmap: 90 bytes × 8 bits = 720 bits |
In the bitmap, 1 means free and 0 means in use. The leftmost bit ($80) of byte 10 represents sector 0, the next bit sector 1, and so on to the rightmost bit of byte 99, sector 719. Wilkinson points out that this is a bug. The 810 drive has no sector 0 but does have a sector 720, so the bitmap is shifted by one, and sector 720 can never be allocated. By the time anyone noticed, tens of thousands of disks used the layout, so it stayed. Some programs took advantage of sector 720 for their own purposes, since DOS never touches it.
Counting the 1 bits in our test disk's bitmap gave 271, matching the free count in bytes 3–4.
4. Directory entries
Each directory sector holds eight 16-byte entries:
| Byte | Contents |
|---|---|
| 0 | Flag byte |
| 1–2 | Length of the file in sectors |
| 3–4 | First sector |
| 5–12 | File name, padded with spaces |
| 13–15 | Extension, padded with spaces |
The flag bits, as documented in De Re Atari:
| Bit | Value | Meaning |
|---|---|---|
| 7 | 128 | Deleted |
| 6 | 64 | In use |
| 5 | 32 | Locked |
| 0 | 1 | Open for output |
A flag of 0 marks an entry that has never been used, and DOS stops searching there. The files on our DOS 2.5 master disk showed 98 ($62): in use, locked, plus bit 1 ($02). The entry's position gives the file number stored in every one of its data sectors: entry 0 of sector 361 is file 0, entry 0 of sector 362 is file 8, and so on.
5. What "delete" really does
Deleting a file does two things only:
- The directory entry's flag is set to 128 ($80). The name, length and first sector stay where they were.
- Each sector in the file's chain is marked free again in the VTOC bitmap, and the free count goes up.
The data sectors are not touched. Until something new is written to those sectors, the whole file is still on the disk, chain and all. That's what DISKFIX.COM's "unerase" option on the DOS 2.5 disk relies on: set the flag back to "in use" and mark the chain's sectors as used again. It can only work if no sector in the chain has been reused, which is why you should stop writing to a disk as soon as you realise you deleted something by mistake.
6. Reading the structures from BASIC
This program reads the VTOC and the eight directory sectors directly through SIO, lists every entry (deleted ones included) with its flag, length and start sector, and then follows the sector chain of the first deleted file it finds, printing sector/file number/bytes used for each link:
10 REM DOS 2 DIRECTORY, INCLUDING DELETED FILES
20 DIM B$(128),N$(11)
30 POKE 1664,104:POKE 1665,32:POKE 1666,89:POKE 1667,228:POKE 1668,96
40 A=ADR(B$):D=0
50 S=360:GOSUB 500
60 ? "SECTORS ";PEEK(A+1)+256*PEEK(A+2);" FREE ";PEEK(A+3)+256*PEEK(A+4)
70 FOR S=361 TO 368:GOSUB 500
80 FOR E=0 TO 7:P=A+E*16:F=PEEK(P):IF F=0 THEN 130
90 N$="":FOR I=5 TO 15:N$(LEN(N$)+1)=CHR$(PEEK(P+I)):NEXT I
100 ? (S-361)*8+E;" ";N$;" ";F;" ";PEEK(P+1)+256*PEEK(P+2);" ";PEEK(P+3)+256*PEEK(P+4);
110 IF F>127 THEN ? " DELETED";:IF D=0 THEN D=PEEK(P+3)+256*PEEK(P+4)
120 ?
130 NEXT E:NEXT S
140 IF D=0 THEN END
150 ? "CHAIN OF FIRST DELETED FILE:":S=D
160 GOSUB 500:H=PEEK(A+125):FN=INT(H/4)
170 ? S;"/";FN;"/";PEEK(A+127);" ";
180 S=(H-FN*4)*256+PEEK(A+126):IF S THEN 160
190 ? :END
500 POKE 768,49:POKE 769,1:POKE 770,82:POKE 771,64
510 POKE 772,A-INT(A/256)*256:POKE 773,INT(A/256)
520 POKE 774,15:POKE 776,128:POKE 777,0
530 POKE 778,S-INT(S/256)*256:POKE 779,INT(S/256)
540 X=USR(1664):RETURN
Line 30 stores a five-byte routine in page 6 (PLA, JSR $E459, RTS) that calls the OS serial I/O routine SIOV. The subroutine at 500 fills the device control block at 768–779: drive 1, command R (82, read), "receive data" (64), buffer address, timeout, 128 bytes and the sector number. Atari BASIC has no AND for bits, so line 160 splits byte 125 with INT(H/4) (file number) and H-FN*4 (the two high bits of the link).
On a DOS 2.5 disk where we had just deleted the file DOSMAN, the program listed the seven locked DOS files with flag 98, the deleted DOSMAN with flag 128, and an earlier deleted AUTORUN.SYS. It then followed AUTORUN.SYS's old chain: 449/7/125 450/7/10, meaning sector 449 belongs to file 7 and is full, and sector 450 holds the last 10 bytes. The deleted file was intact.
The program only reads, but treat any experiment with writing sectors with great care. One wrong sector number in a write command can destroy the directory. Practise on an ATR copy in an emulator.
7. Using the knowledge
- ERROR 164 on a file: a broken chain. A link points into a sector owned by another file. A sector editor, or a program like the one above, shows where the chain goes wrong.
- Free count looks wrong: the bitmap and the count in bytes 3–4 have drifted apart, usually after a crash during writing. Copying the files to a freshly formatted disk rebuilds everything.
- "Disk full" with sectors apparently free: on DOS 2.0S an enhanced-density disk shows only its first 720 sectors.
- NOTE/POINT positions are simply sector and byte values in this scheme, which is why DOS can check them against the file number (see Working with Disk Files in Atari BASIC).
Troubleshooting
- Status 138 from the program: no drive 1 answered. Check that the disk is in D1:.
- Names print strangely: the entry is unused or deleted and holds leftovers. Check the flag first.
- The chain loops forever: a damaged disk can link back on itself. Stop after the file's length (bytes 1–2 of the entry) in your own tools.
- Different numbers on MyDOS or SpartaDOS disks: MyDOS extends the bitmap for larger disks and adds subdirectories, and SpartaDOS uses a completely different file system.
Further reading
- Bill Wilkinson, Inside Atari DOS (COMPUTE! Books, 1982): chapter 2 "Disk Organization", and the GETSECTOR/FRESECT routines.
- De Re Atari (Atari, Inc., 1982), chapter 9: VTOC, directory and sector formats.
- On this site: SIO Explained, Atari DOS 2.5: A Practical Guide, Working with Disk Files in Atari BASIC, Atari 8-bit File Formats Explained.
Credits
- Picture: The example program reading the VTOC and directory sectors directly, showing deleted entries and following a deleted file's sector chain. — Program authors; screenshot by the site
- Bill Wilkinson, Inside Atari DOS — Chapter 2 Disk Organization; Chapter 16 Directory Searching; Chapter 19 Get and Free Sector; Chapter 20 The Boot Process — Bill Wilkinson; AtariArchives.org
- De Re Atari, Chapter 9 — VTOC, file directory format and flag bits, FMS file sector format — AtariArchives.org
- Mapping the Atari — 768-779 DCB, 58457 SIOV — AtariArchives.org
