Filesystem on TurboVision

Deterministic DIR Output as an Operational Contract

Tue, 10 Mar 2026 00:00:00 +0000

The story starts at 23:14 in a room with two beige towers, one half-dead fluorescent tube, and a whiteboard covered in hand-written file counts. We had one mission: rebuild a damaged release set from mixed backup disks and compare it against a known-good manifest.

On paper, that sounds easy. In practice, it meant parsing DIR output across different machines, each configured slightly differently, each with enough personality to make automation fail at the worst moment.

By 23:42 we had already hit the first trap. One machine produced DIR output that looked “normal” to a human and ambiguous to a parser. Another printed dates in a different shape. A third had enough local customization that every assumption broke after line three. We were not failing because DOS was bad. We were failing because we had not written down what “correct output” meant.

That night we stopped treating DIR as a casual command and started treating it as an API contract.

This article is that deep dive: why a deterministic profile matters, how to structure it, and how to parse it without superstitions.

The turning point: formatting is behavior

In modern systems, people accept that JSON schemas and protocol contracts are architecture. In DOS-era workflows, plain text command output played that same role. If your automation consumed command output, formatting was behavior.

Our internal profile locked one specific command shape:

DIR [drive:][path][filespec]
default long listing
no /W, no /B, no formatting switches
fixed US date/time rendering (MM-DD-YY, h:mma / h:mmp)

That scoping decision solved half the problem. We stopped pretending one parser should support every possible switch/locale and instead declared a strict operating envelope.

A canonical listing is worth hours of debugging

The profile included a canonical example and we used it as a fixture:

 Volume in drive C has no label
 Volume Serial Number is 3F2A-19C0

 Directory of C:\RETROLAB

AUTOEXEC BAT      1024 03-09-96  9:40a
BIN              <DIR> 03-08-96  4:15p
DOCS             <DIR> 03-07-96 11:02a
README   TXT       512 03-09-96 10:20a
SRC              <DIR> 03-07-96 11:04a
TOOLS    EXE     49152 03-09-96 10:21a
       3 File(s)      50,688 bytes
       3 Dir(s)  14,327,808 bytes free

Why include this in a spec? Because examples settle debates that prose cannot. When two engineers disagree, the fixture wins.

The 38-column row discipline

The core entry template was fixed-width:

`1`	`%-8s %-3s %8s %8s %6s`

That yields exactly 38 columns:

columns 1..8: basename (left-aligned)
column 9: space
columns 10..12: extension (left-aligned)
columns 13..14: spaces
columns 15..22: size-or-dir (right-aligned)
column 23: space
columns 24..31: date
column 32: space
columns 33..38: time (right-aligned)

Once you adopt positional parsing instead of regex guesswork, DIR lines become boring in the best way.

Why this works even on noisy nights

Fixed-width parsing has practical advantages under pressure:

no locale-sensitive token splitting for date/time columns
no ambiguity between <DIR> and size values
deterministic handling of one-digit vs two-digit hour
easy visual validation during manual triage

At 01:12, when you are diffing listings by eye and caffeine alone, “column 15 starts the size field” is operational mercy.

Header and footer are part of the protocol

Many parsers only parse entry rows and ignore header/footer. That is a missed opportunity.

Our profile explicitly fixed header sequence:

volume label line (is <LABEL> or has no label)
serial line (XXXX-XXXX, uppercase hex)
blank line
Directory of <PATH>
blank line

And footer sequence:

file totals: %8u File(s) %11s bytes
dir/free totals: %8u Dir(s) %11s bytes free

Those two footer lines are not decoration. They are integrity checks. If parsed file count says 127 and footer says 126, stop and investigate before touching production disks.

Parsing algorithm we actually trusted

This is the skeleton we converged on in Turbo Pascal style:

type
  TDirEntry = record
    BaseName: string[8];
    Ext: string[3];
    IsDir: Boolean;
    SizeBytes: LongInt;
    DateText: string[8]; { MM-DD-YY }
    TimeText: string[6]; { right-aligned h:mma/h:mmp }
  end;

function TrimRight(const S: string): string;
var
  I: Integer;
begin
  I := Length(S);
  while (I > 0) and (S[I] = ' ') do Dec(I);
  TrimRight := Copy(S, 1, I);
end;

function ParseEntryLine(const L: string; var E: TDirEntry): Boolean;
var
  NameField, ExtField, SizeField, DateField, TimeField: string;
  Code: Integer;
begin
  ParseEntryLine := False;
  if Length(L) < 38 then Exit;

  NameField := Copy(L, 1, 8);
  ExtField  := Copy(L, 10, 3);
  SizeField := Copy(L, 15, 8);
  DateField := Copy(L, 24, 8);
  TimeField := Copy(L, 33, 6);

  E.BaseName := TrimRight(NameField);
  E.Ext      := TrimRight(ExtField);
  E.DateText := DateField;
  E.TimeText := TimeField;

  if TrimRight(SizeField) = '<DIR>' then
  begin
    E.IsDir := True;
    E.SizeBytes := 0;
  end
  else
  begin
    E.IsDir := False;
    Val(TrimRight(SizeField), E.SizeBytes, Code);
    if Code <> 0 then Exit;
  end;

  ParseEntryLine := True;
end;

This parser is intentionally plain. No hidden assumptions, no dynamic heuristics, no “best effort.” It either matches the profile or fails loudly.

Edge cases that must be explicit

The spec was strict about awkward but common cases:

extensionless files: extension field is blank (three spaces in raw row)
short names/exts: right-padding in fixed fields
directories always use <DIR> in size field
if value exceeds width, allow rightward overflow; never truncate data

The overflow rule is subtle and important. Truncation creates false data, and false data is worse than ugly formatting.

Counting bytes: grouped vs ungrouped is not random

A detail teams often forget:

entry SIZE_OR_DIR file size is decimal without grouping
footer byte totals are grouped with US commas in this profile

That split looks cosmetic until a parser accidentally strips commas in one place but not the other. If totals are part of your acceptance gate, normalize once and test it with fixtures.

The fictional incident that made it real

At 02:07 in our story, we finally had a clean parse on machine A. We ran the same process on machine B, then compared manifests. Everything looked perfect except one tiny mismatch: file count agreed, byte count differed by 1,024.

Old us would have guessed corruption and started copying disks again.

Spec-driven us inspected footer math first, then entry parse, then source listing capture. The issue was not corruption. One listing had accidentally included a generated staging file from a side directory because the operator typed a wildcard path incorrectly.

The deterministic header (Directory of ...) and footer checks caught it in minutes.

No drama. Just protocol discipline.

What this teaches beyond DOS

The strongest lesson is not “DOS output is neat.” The lesson is operational:

any text output consumed by tools should be treated as a contract
contracts need explicit scope and out-of-scope declarations
examples + field widths + sequence rules beat vague descriptions
integrity lines (counts/totals) should be first-class validation points

That mindset scales from floppy-era rebuild scripts to modern CI logs and telemetry processors.

Implementation checklist for your own parser

If you want a stable implementation from this profile:

enforce command profile (no unsupported switches)
parse header in strict order
parse entry rows by fixed columns, not token split
parse footer totals and cross-check with computed values
fail explicitly on profile deviation
keep canonical fixture listings in version control

This gives you deterministic behavior and debuggable failures.

Closing scene

At 03:18 we printed two manifests, one from recovered media and one from archive baseline, and compared them line by line. For the first time that night, we trusted the result.

Not because the room got quieter.
Not because the disks got newer.
Because the contract got clearer.

The old DOS prompt did what old prompts always do: it reflected our discipline back at us.

VFAT to 8.3: The Shortname Rules Behind the Curtain

Tue, 10 Mar 2026 00:00:00 +0000

The second story begins with a floppy label that looked harmless:

RELEASE_NOTES_FINAL_REALLY_FINAL.TXT

By itself, that filename is only mildly annoying. Inside a mixed DOS/Windows pipeline in 1990s tooling, it can become a release blocker.

Our fictional team learned this in one long weekend. The packager ran on a VFAT-capable machine. The installer verifier ran in a strict DOS context. The build ledger expected 8.3 aliases. Nobody had documented the shortname translation rules completely. Everybody thought they “basically knew” them.

“Basically” lasted until the audit script flagged twelve mismatches that were all technically valid and operationally catastrophic.

This article is the deep dive we wish we had then: how long names become 8.3 aliases, how collisions are resolved, and how to build deterministic tooling around those rules.

First principle: translate per path component

The most important rule is easy to miss:

Translation happens per single path component, not on the full path string.

That means each directory name and final file name is handled independently. If you normalize the entire path in one pass, you will eventually generate aliases that cannot exist in real directory contexts.

In practical terms:

C:\SRC\Very Long Directory\My Program Source.pas
is translated component-by-component, each with its own collision scope

That “collision scope” phrase matters. Uniqueness is enforced within a directory, not globally across the volume.

Fast path: already legal 8.3 names stay as-is

If the input is already a legal short name after OEM uppercase normalization, use that 8.3 form directly (uppercase).

This avoids unnecessary alias churn and preserves operator expectations. A file named CONFIG.SYS should not become something novel just because your algorithm always builds FIRST6~1.

Teams that skip this rule create avoidable incompatibilities.

When alias generation is required

If the name is not already legal 8.3, generate alias candidates using strict steps.

The baseline candidate pattern is:

FIRST6~1.EXT

Where:

FIRST6 is normalized/truncated basename prefix
~1 is initial numeric tail
.EXT is extension if one exists, truncated to max 3

No extension? Then no trailing dot/extension segment.

Dot handling is where most bugs hide

Real filenames can contain multiple dots, trailing dots, and decorative punctuation. The rules must be explicit:

skip leading . characters
allow only one basename/extension separator in 8.3
prefer the last dot that has valid non-space characters after it
if name ends with a dot, ignore that trailing dot and use a previous valid dot if present

This is the difference between deterministic behavior and parser folklore.

Example intuition:

report.final.v3.txt -> extension source is last meaningful dot before txt
archive. -> trailing dot is ignored; extension may end up empty

Character legality and normalization

Normalization from the spec includes:

remove spaces and extra dots
uppercase letters using active OEM code page semantics
drop characters that are not representable/legal for short names

Disallowed characters include control chars and:

" * + , / : ; < = > ? [ \ ] |

A critical note from the rules:

Microsoft-documented NT behavior: [ ] + = , : ; are replaced with _ during short-name generation
other illegal/superfluous characters are removed

If your toolchain mixes “replace” and “remove” without policy, you will drift from expected aliases.

Collision handling is an algorithm, not a guess

The collision rule set is precise:

try ~1
if occupied, try ~2, ~3, …
as tail digits grow, shrink basename prefix so total basename+tail stays within 8 chars
continue until unique in the directory

That means ~10 and ~100 are not formatting quirks. They force basename compaction decisions.

A common implementation failure is forgetting to shrink prefix when suffix width grows. The result is invalid aliases or silent truncation.

A deterministic translator skeleton

The following Pascal-style pseudocode keeps policy explicit:

function MakeShortAlias(const LongName: string; const Existing: TStringSet): string;
var
  BaseRaw, ExtRaw, BaseNorm, ExtNorm: string;
  Tail, PrefixLen: Integer;
  Candidate: string;
begin
  SplitUsingDotRules(LongName, BaseRaw, ExtRaw);   { skip leading dots, last valid dot logic }
  BaseNorm := NormalizeBase(BaseRaw);              { remove spaces/extra dots, uppercase, legality policy }
  ExtNorm  := NormalizeExt(ExtRaw);                { uppercase, legality policy, truncate to 3 }

  if IsLegal83(BaseNorm, ExtNorm) and (not Existing.Contains(Compose83(BaseNorm, ExtNorm))) then
  begin
    MakeShortAlias := Compose83(BaseNorm, ExtNorm);
    Exit;
  end;

  Tail := 1;
  repeat
    PrefixLen := 8 - (1 + Length(IntToStr(Tail))); { room for "~" + digits }
    if PrefixLen < 1 then PrefixLen := 1;
    Candidate := Copy(BaseNorm, 1, PrefixLen) + '~' + IntToStr(Tail);
    Candidate := Compose83(Candidate, ExtNorm);
    Inc(Tail);
  until not Existing.Contains(Candidate);

  MakeShortAlias := Candidate;
end;

This intentionally leaves NormalizeBase, NormalizeExt, and SplitUsingDotRules as separate units so policy stays testable.

Table-driven tests beat intuition

Our fictional team fixed its pipeline by building a test corpus, not by debating memory:

Input Component                         Expected Shape
--------------------------------------  ------------------------
README.TXT                              README.TXT
very long filename.txt                  VERYLO~1.TXT
archive.final.build.log                 ARCHIV~1.LOG
...hiddenprofile                        HIDDEN~1
name with spaces.and.dots...cfg         NAMEWI~1.CFG

The exact alias strings can vary with existing collisions and code-page/legality policy details, but the algorithmic behavior should not vary.

Why this matters in operational pipelines

Shortname translation touches many workflows:

installer scripts that reference legacy names
backup/restore verification against manifests
cross-tool compatibility between VFAT-aware and strict 8.3 utilities
reproducible release artifacts

If alias generation is non-deterministic, two developers can build “same version” media with different effective filenames.

That is a release-management nightmare.

The fictional incident response

In our story, the break happened during a Friday packaging run. By Saturday morning, three teams had three conflicting explanations:

“the verifier is wrong”
“Windows generated weird aliases”
“someone copied files manually”

By Saturday afternoon, a tiny deterministic translator plus collision-aware tests cut through all three theories. The verifier was correct, alias generation differed between tools, and manual copies had introduced namespace collisions in one directory.

Nobody needed blame. We needed rules.

Subtle rule: legality depends on OEM code page

One more important caveat from the spec:

Uppercasing and character validity are evaluated in active OEM code page context.

That means “works on my machine” can still fail if code-page assumptions differ. For strict reproducibility, pin the environment and test corpus together.

Practical implementation checklist

For a robust translator:

process one path component at a time
implement legal-8.3 fast path first
codify dot-selection/trailing-dot behavior exactly
separate remove-vs-replace character policy clearly
enforce extension max length 3
implement collision tail growth with dynamic prefix shrink
ship fixture tests with occupied-directory scenarios

That last point is non-negotiable. Most alias bugs only appear under collision pressure.

Closing scene

Our weekend story ends around 01:03 on Sunday. The final verification pass prints green across every directory. The whiteboard still looks chaotic. The room still smells like old plastic and instant coffee. But now the behavior is explainable.

Long names can still be expressive. Short names can still be strict. The bridge between them does not need magic. It needs documented rules and testable translation.

In DOS-era engineering, that is usually the whole game: reduce mystery, increase repeatability, and let simple tools carry serious work.