SCRYDOSBox-XReferenceFilesguest_file

DOSBox-XFiles

guest_file

Check a file the DOS program was meant to write on a mounted drive: whether this run wrote it, its size and its hash.

guest_file(path)

Try it

It needs a DOS program that writes a file on a mounted drive, which neither Bricks nor Minesweeper does. The reply shown comes from a test program that is not distributed.
Ask

Did the program write OUT.TXT during this run?

Call
guest_file(path="$TMPDIR/dosbox-x-live-matrix-<run>/jobs-scratch/Y/n1-dosio/OUT.TXT")
Reply 4 of 7 fields
{
  "state": "written",
  "before": {"exists": false},
  "bytes": 4,
  "sha256": "580175b2969134a0d8c6f325b442c6d25cf5b10f0643150ed45ffd3a8905bcba"
}

written means this run wrote the file. Nothing was there before the emulator booted (exists is false), and the file now holds 4 bytes.

The whole reply
JSON
{
  "summary": "guest_file $TMPDIR/dosbox-x-live-matrix-<run>/jobs-scratch/Y/n1-dosio/OUT.TXT: written, 4 bytes",
  "status": "ok",
  "path": "$TMPDIR/dosbox-x-live-matrix-<run>/jobs-scratch/Y/n1-dosio/OUT.TXT",
  "state": "written",
  "before": {"exists": false},
  "bytes": 4,
  "sha256": "580175b2969134a0d8c6f325b442c6d25cf5b10f0643150ed45ffd3a8905bcba"
}

Arguments

path string, required
The file on your disk, one of the paths given to start(guest_files=). An absolute path, or one starting with ~.

What comes back

state
written when this run wrote the file. absent, empty, unchanged and unreadable come as a refusal.
bytes
The file's size now.
sha256
The SHA-256 of the file now.
before
What was there before the emulator booted: exists and, when it did, its bytes and sha256.
same_bytes
true when the run wrote the file again with the bytes it already held.
All 6 reply fields
  • before (object)
  • bytes (integer)
  • path (string)
  • same_bytes (boolean)
  • sha256 (string)
  • state (string)

What it refuses

Why it works this way

A DOS program hands a result back as a file on a mounted drive. start(guest_files=) records each file's size, modification time and SHA-256 before the emulator boots, and this tool compares the file with that record.

A file left by an earlier run passes any test for existence, which is why unchanged is refused. A file written again with the same bytes has a new time, so it is written, with same_bytes.

A file the program still holds open may not have its bytes yet: the emulator buffers them until DOS closes the file.

More on why

close checks each file again after the emulator has exited. On a clean quit every file the program left open has been closed and written out; an emulator that was killed may have left bytes unwritten.

A file your computer cannot read, such as a name the program made a directory of, is unreadable, and close still closes.

The contract your client receives
Text
What the guest left at `path`, a host file `start(guest_files=)` fingerprinted before
the emulator booted: `absent`, `empty`, `unchanged` (the bytes and time from before the
run) or `written`. Reads the host's file, so it answers with the guest running or after
`close`.

Reply: `path`, `state`, `bytes`, `sha256`, `before` (`exists`, `bytes`, `sha256`),
`same_bytes` (written again with the bytes it held). INVALID `readback_refused` on the
first three, which hand nothing back; a path `start` did not name is refused.

Reference: REFERENCE.md, Files inside DOS.
Tools