8.8.1.1.1.2.16. Symbols

interface Symbols()
add(fullPath: string)

Loads only the symbol information for the provided file and adds it to the currently loaded debug information.

session.symbols.add("C:/my_project/Debug/example.out");
Parameters:

  • fullPath (string) -- The full path to the file.

Return type:

void

addWithOffset(fullPath: string, codeOffset: bigint | number | string, dataOffset: bigint | number | string, relativeOffset?: boolean)

Like :js:meth:~add but code and data are relocated as specified.

// Suppose that first code section in example.out starts at 0x20000000 in
// target memory, and its first data section starts at 0x1000.

// If we want to shift the code symbols by 0x2000 and the data symbols by 0x800
// we can do either of the following:
session.symbols.addWithOffset("C:/my_project/Debug/example.out", 0x20002000, 0x1800, false);
session.symbols.addWithOffset("C:/my_project/Debug/example.out", 0x2000, 0x800, true);
Parameters:

  • fullPath (string) -- The full path to the file.

  • codeOffset (bigint | number | string) -- The offset to apply to code locations.

  • dataOffset (bigint | number | string) -- The offset to apply to data locations.

  • relativeOffset (boolean | null) -- Whether the offsets are relative (default: false).

Return type:

void

load(fullPath: string)

Loads only the symbol information for the provided file and replaces the currently loaded symbol information with it. This is equivalent to calling :js:meth:~unloadAllSymbols followed by :js:meth:~add.

session.symbols.load("C:/my_project/Debug/example.out");
Parameters:

  • fullPath (string) -- The full path to the file.

Return type:

void

loadWithOffset(fullPath: string, codeOffset: bigint | number | string, dataOffset: bigint | number | string, relativeOffset?: boolean)

Like :js:meth:~load but code and data are relocated as specified.

// Suppose that first code section in example.out starts at 0x20000000 in
// target memory, and its first data section starts at 0x1000.
session.symbols.load("C:/my_project/Debug/example.out");

session.symbols.getAddress("main");  // 0x200001C0n  (for example)
session.symbols.getAddress("g_my_var");  // 0x1008n  (for example)

// If we want to shift the code symbols by 0x2000 and the data symbols by 0x800
// we can do either of the following:
session.symbols.loadWithOffset("C:/my_project/Debug/example.out", 0x2000, 0x800, true);
session.symbols.loadWithOffset("C:/my_project/Debug/example.out", 0x20002000, 0x1800, false);

session.symbols.getAddress("main");  // 0x200021C0n
session.symbols.getAddress("g_my_var");  // 0x1808n
Parameters:

  • fullPath (string) -- The full path to the file.

  • codeOffset (bigint | number | string) -- The offset to apply to code locations.

  • dataOffset (bigint | number | string) -- The offset to apply to data locations.

  • relativeOffset (boolean | null) -- Whether the offsets are relative (default: false).

Return type:

void

remove(fullPath: string)

Removes the symbol information defined in the provided file. Symbol information from other files is not affected.

session.symbols.remove("C:/my_project/Debug/example.out");
Parameters:

  • fullPath (string) -- The full path to the file.

Return type:

void

unloadAllSymbols()

Unloads all symbol information. This is equivalent to calling :js:meth:~remove for all currently loaded files.

session.symbols.unloadAllSymbols();
Return type:

void

getAddress(symbol: string)

Returns the address of the provided symbol if it exists.

// Get the address of the main function
const address = session.symbols.getAddress("main");

// Get the address of a global variable
const address = session.symbols.getAddress("my_global");
Parameters:

  • symbol (string) -- The name of the symbol to lookup.

Returns:

The address of the symbol.

Return type:

bigint | number | string | null

lookupSymbols(start: DSLocation, length: bigint | number | string | null)

Returns the names of all symbols at the provided location, or in the provided range.

// Look up symbols at 0x100
const symbols = session.symbols.lookupSymbols(0x100);

// Look up symbols in the range 0x100 to 0x140
const symbols = session.symbols.lookupSymbols(0x100, 0x40);
Parameters:

  • start (DSLocation) -- The location at which to look for symbols.

  • length (bigint | number | string | null) -- The length of range in which to look for symbols (defaults to 0).

Returns:

A list of symbol names.

Return type:

string[]