SCRYDOSBox-XReferenceNamessymbols_findAlso in MAME

DOSBox-XNames

symbols_find

Find a symbol's address by its name, or find which symbol an address falls in.

symbols_find(name="", offset=null, section=null, linear=null, limit=10)

Try it

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

Which symbols start with "ball"?

Call
symbols_find(name="ball")
Reply 3 of 6 fields
{
  "summary": "symbols_find ball: 5 symbols",
  "symbols_total": 5,
  "truncated": false
}

Five symbols start with ball, and all five came back. The whole reply, below, lists each with its offset and its linear address.

The whole reply
JSON
{
  "summary": "symbols_find ball: 5 symbols",
  "status": "ok",
  "query": "ball",
  "symbols_total": 5,
  "symbols": [
    {
      "name": "ball_rect",
      "kind": "T",
      "offset": "0x398",
      "section": -1,
      "addr": "0x00009188",
      "idle": false
    },
    {
      "name": "ball_x",
      "kind": "D",
      "offset": "0x621",
      "section": -1,
      "addr": "0x00009411",
      "idle": false
    },
    {
      "name": "ball_y",
      "kind": "D",
      "offset": "0x623",
      "section": -1,
      "addr": "0x00009413",
      "idle": false
    },
    {
      "name": "ball_dx",
      "kind": "D",
      "offset": "0x625",
      "section": -1,
      "addr": "0x00009415",
      "idle": false
    },
    {
      "name": "ball_dy",
      "kind": "D",
      "offset": "0x627",
      "section": -1,
      "addr": "0x00009417",
      "idle": false
    }
  ],
  "truncated": false
}

Arguments

name string, default ""
The symbol to look up, case ignored. An exact match wins; with none, every symbol that starts with it is listed, by section and offset.
offset integer or string, optional
An offset as the toolchain wrote it, before any base. The reply is the nearest symbol at or below it.
section integer, optional
The section offset is in, by its index, for a table loaded with section_bases. A table without sections needs none.
linear integer or string, optional
A linear address, never a SEG:OFF: an integer or 0x text. The reply is the nearest symbol at or below it.
limit integer (>= 1, <= 50), default 10
How many symbols a name lookup lists: 1 to 50. Left out, 10; a lookup by address does not use it.

What comes back

symbols
By name: the first limit matches, each with name, kind, offset, section, addr and idle.
symbols_total
By name: how many symbols matched.
truncated
By name: true when more matched than symbols lists.
name
By address: the nearest symbol at or below the address, with the fields of a row of symbols.
delta
By address: how many bytes the address is past that symbol's start.
addr
The symbol's linear address: its offset plus the base the table was loaded at.
All 11 reply fields
  • addr (string)
  • delta (integer)
  • idle (boolean)
  • kind (string)
  • name (string)
  • offset (string)
  • query (string)
  • section (integer)
  • symbols (array)
  • symbols_total (integer)
  • truncated (boolean)

What it refuses

Why it works this way

The table is the server's own copy, not read from the machine, so the lookup answers while the program runs. Its names are whole, never cut to the debugger's 15 characters, and leave out what the load's filters dropped.

delta is a distance past the symbol's start because the table holds no sizes. kind is nm's letter for the symbol's type, mostly ? from a link map. idle is Borland's own mark on a row, always false for nm and GNU maps.

The contract your client receives
Text
Look a symbol up in the table `symbols_load` kept. `name`: exact, else prefix matches by
section and offset, case ignored, each in the spelling the map gave, up to `limit`.
`offset` or `linear` (each `0x` hex or an integer), with `section`: the nearest symbol
at or below.

Reply: `query`; by name, `symbols_total`, `symbols` (`name`, `offset` as `0x` hex, `addr`),
`truncated`;
by address, the symbol's fields and `delta`. INVALID: no table.
Tools