SCRYDOSBox-XReferenceReadmemdumpAlso in MAME

DOSBox-XRead

memdump

Write a range of memory to a file, for ranges too large to read into the conversation.

memdump(ref, length, dest)

Try it

On Bricks, the game this repository builds, stopped on its play screen before any brick falls, with its symbols loaded.
Ask

Save the 60 bytes of the wall of bricks to a file.

Call
memdump(ref="bricks", length=60, dest="./tmp/demos/tour/files/wall.bin")
Reply 5 of 7 fields
{
  "summary": "memdump bricks: 60 bytes to ./tmp/demos/tour/files/wall.bin",
  "seg_off": "08DF:0000062C",
  "length": 60,
  "path": "./tmp/demos/tour/files/wall.bin",
  "bytes": 60
}

The file holds 60 bytes, as asked: bytes equals length. path is where it was written.

The whole reply
JSON
{
  "summary": "memdump bricks: 60 bytes to ./tmp/demos/tour/files/wall.bin",
  "status": "ok",
  "ref": "bricks",
  "seg_off": "08DF:0000062C",
  "length": 60,
  "path": "./tmp/demos/tour/files/wall.bin",
  "bytes": 60
}

Arguments

ref string, required
Where the range begins: a symbol or a SEG:OFF address.
length integer, required
How many bytes to write, 1 or more.
dest string, required
The file to create: an absolute or ~-led path, not there yet.

What comes back

path
The file as written; a note says so when its name is not the one dest gave.
bytes
The file's size, which equals length.
seg_off
The address ref resolved to, as segment and offset.
All 5 reply fields
  • bytes (integer)
  • length (integer)
  • path (string)
  • ref (string)
  • seg_off (string)

What it refuses

Why it works this way

The debugger writes the dump in the emulator's working folder, as MCPDUMP.BIN, and the server moves it to dest. A dump file already there is somebody's, so the call refuses it and deletes nothing; a dangling link counts. A dest in that folder is refused too: once moved, the file could not be told from a leftover.

Past offset 0xFFFF the debugger would reread the start of a 16-bit segment, or write zeros past a segment's limit, and still report success. So in real mode a long range is read in 64 KiB pieces, up to FFFF:FFFF. In protected mode it is checked against the segment's descriptor first.

Inside offsets 0 to 0xFFFF the segment's limit is not checked, and the debugger writes zeros past it.

More on why

Some builds of DOSBox-X name the file MEMDUMP.BIN themselves, in the working folder or in the captures folder, so a leftover of that name is refused in both. A dest is compared with those names on the file system, not by spelling. captures_dir is not where a dump lands.

Deleting a leftover first would not be safer. A delete that failed quietly would leave the old file, the debugger would still report success, and a stale dump would come back as new.

The contract your client receives
Text
`length` bytes from `ref` (a symbol or `SEG:OFF`) to the new file `dest` (absolute or
`~`-led).

Reply: `ref`, `seg_off`, `length`, `path`, `bytes`. Refused: a dump file already where the
debugger writes or at `dest`, a `dest` directly in that directory, an absent or ambiguous
symbol; in protected mode a 16-bit segment, a range past its limit, or no descriptor.
Tools