SCRYDOSBox-XReferenceReadfindAlso in MAME

DOSBox-XRead

find

Find every address in a range of memory that holds a given sequence of bytes.

find(data_hex, ref, length)

Try it

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

Find where the program holds the text SCORE.

Call
find(data_hex="53434f5245", ref="start", length=1384)
Reply 5 of 9 fields
{
  "summary": "find start: 1 hit of 53434f5245 in 1384 bytes",
  "span": {"from": "08DF:00000100", "length": 1384, "source": "ref+length"},
  "hits": ["08DF:00000601"],
  "hits_total": 1,
  "truncated": false
}

The five bytes of SCORE are at one address, 08DF:00000601. span says which bytes were searched: 1384 from 08DF:00000100, the symbol start.

The whole reply
JSON
{
  "summary": "find start: 1 hit of 53434f5245 in 1384 bytes",
  "status": "ok",
  "ref": "start",
  "seg_off": "08DF:00000100",
  "length": 1384,
  "span": {"from": "08DF:00000100", "length": 1384, "source": "ref+length"},
  "hits": ["08DF:00000601"],
  "hits_total": 1,
  "truncated": false
}

Arguments

data_hex string, required
The bytes to look for, as hex: whole bytes, at least one.
ref string, required
Where the range begins: a symbol or a SEG:OFF address.
length integer, required
How many bytes to search from ref.

What comes back

hits
The addresses where the bytes begin, as SEG:OFF, at most 400; past that, the highest are kept.
hits_total
How many addresses hold the bytes, listed or not.
truncated
true when there are more hits than hits lists.
span
The bytes that were searched, as from, length and source, so zero hits says where there are none. source is always ref+length.
All 7 reply fields
  • hits (array)
  • hits_total (integer)
  • length (integer)
  • ref (string)
  • seg_off (string)
  • span (object)
  • truncated (boolean)

What it refuses

Why it works this way

The debugger has no search for bytes. So the range is read as memdump reads it, into a temporary file that is gone before the reply, and searched there.

In real mode a hit past offset 0xFFFF is written with a segment of its own, since no offset reaches it from the segment you gave.

The contract your client receives
Text
Every address holding `data_hex` (whole hex bytes) in `length` bytes from `ref`; both
required. `memdump`'s refusals apply. For a value narrowed over time use `scan`.

Reply: `ref`, `seg_off`, `length`, `span`, `hits` (`SEG:OFF`, at most 400, highest kept),
`hits_total`, `truncated`.
Tools