SCRYDOSBox-XReferenceNamessymbols_findAlso in MAME
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
Which symbols start with "ball"?
symbols_find(name="ball"){
"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
{
"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
offsetis in, by its index, for a table loaded withsection_bases. A table without sections needs none. - linear integer or string, optional
- A linear address, never a
SEG:OFF: an integer or0xtext. 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
limitmatches, each withname,kind,offset,section,addrandidle. - symbols_total
- By name: how many symbols matched.
- truncated
- By name:
truewhen more matched thansymbolslists. - 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
offsetplus 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
- More or fewer than one of
name,offsetandlinear: one question per call (bad_argument). - A session with no table loaded (
no_channel). - An
offsetwith nosectionon a table with sections, or asectionon a table without (bad_argument). - An address below every symbol, or a section the table does not have (
unknown_ref).
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.
Related tools
The contract your client receives
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.