# fileio_trace

> **Tool `tools/dos/fileio_trace.py`** (program, 16-bit DOS). Turn a DOSBox-X file log into a per-file map of reads: which file, at which offset, how many bytes, in what order.

Run it with `./gameframe run fileio_trace ARGS` or `python3 tools/dos/fileio_trace.py`. [Source on GitHub](https://github.com/tanepiper/game-frame/blob/main/tools/dos/fileio_trace.py).

## Its own help

This is the help text in the tool itself, as `./gameframe tool fileio_trace` prints it.

```text
Turn a DOSBox-X file log into a per-file map of reads: which file, at which offset, how many
bytes, in what order. The read sizes of a file that a program reads field by field (Pascal
BlockRead, C fread of a struct member) are the file's record layout, measured.

Usage: fileio_trace.py DOSBOX_LOG [--file NAME] [--game DIR] [--raw]

  DOSBOX_LOG   the log written by scripts/dosbox-run.sh --fileio (analysis/dosbox/dosbox.log)
  --file NAME  only this file (case does not matter)
  --game DIR   the game folder, to resolve seeks from the end of a file (SEEK_END)
  --raw        every read on its own line, instead of grouping repeated patterns

Prints, for each file in the order it was first opened: the open count and mode, then the reads
as "offset +size". A run of identical patterns is shown once with its repeat count, for example
"0x0020: [2, 1, 4] x 120 (stride 7)", which reads as a table of 120 seven-byte records.
Evidence from this tool is *measured* (the original program ran); name the run's inputs.
It does not see memory-mapped or BIOS disk access, and the log has no timestamps beyond
DOSBox-X's own cycle counter.
```

## Named by

Skills: [re-observe](/skills/re-observe), [re-format](/skills/re-format).