SCRYDOSBox-XReferenceReadmemdumpAlso in MAME
memdump
Write a range of memory to a file, for ranges too large to read into the conversation.
memdump(ref, length, dest)
Try it
Save the 60 bytes of the wall of bricks to a file.
memdump(ref="bricks", length=60, dest="./tmp/demos/tour/files/wall.bin"){
"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
{
"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:OFFaddress. - 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
notesays so when its name is not the onedestgave. - bytes
- The file's size, which equals
length. - seg_off
- The address
refresolved to, as segment and offset.
All 5 reply fields
bytes(integer)length(integer)path(string)ref(string)seg_off(string)
What it refuses
- A dump file already in the emulator's working folder, or a file already at
dest(bad_argument). - A
destdirectly in the emulator's working folder, or at or under one of the debugger's own file names (bad_argument). - In protected mode: a range past
0xFFFFon a 16-bit segment, a range past the segment's limit, or a selector with no descriptor (bad_argument). - In real mode: a range that ends past
FFFF:FFFF(bad_argument). - A symbol the loaded table lacks (
unknown_ref), or one it holds twice (ambiguous_ref). - A dump that is not
lengthbytes (readback_refused).
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.
Related tools
The contract your client receives
`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.