SCRYDOSBox-XReferenceFilesguest_file
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
Did the program write OUT.TXT during this run?
guest_file(path="$TMPDIR/dosbox-x-live-matrix-<run>/jobs-scratch/Y/n1-dosio/OUT.TXT"){
"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
{
"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
writtenwhen this run wrote the file.absent,empty,unchangedandunreadablecome 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:
existsand, when it did, itsbytesandsha256. - same_bytes
truewhen 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
- A path that
start(guest_files=)did not name (bad_argument). - A file that is
absent,empty,unchangedsince before the run, orunreadable(readback_refused).
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.
Related tools
The contract your client receives
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.