Skip to content

libdebug.data.symbol_list

SymbolList

Bases: list

A list of symbols in the target process.

Source code in libdebug/data/symbol_list.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
class SymbolList(list):
    """A list of symbols in the target process."""

    def __init__(self: SymbolList, symbols: list[Symbol], maps_source: InternalDebugger | Snapshot) -> None:
        """Initializes the SymbolDict."""
        super().__init__(symbols)

        self._maps_source = maps_source

    def _search_by_address(self: SymbolList, address: int) -> list[Symbol]:
        """Searches for a symbol by address.

        Args:
            address (int): The address of the symbol to search for.

        Returns:
            list[Symbol]: The list of symbols that match the specified address.
        """
        # Find the memory map that contains the address
        if maps := self._maps_source.maps.filter(address):
            address -= maps[0].start
        else:
            raise ValueError(
                f"Address {address:#x} does not belong to any memory map. You must specify an absolute address.",
            )
        return [symbol for symbol in self if symbol.start <= address < symbol.end]

    def _search_by_name(self: SymbolList, name: str) -> list[Symbol]:
        """Searches for a symbol by name.

        Args:
            name (str): The name of the symbol to search for.

        Returns:
            list[Symbol]: The list of symbols that match the specified name.
        """
        exact_match = []
        no_exact_match = []
        # We first want to list the symbols that exactly match the name
        for symbol in self:
            if symbol.name == name:
                exact_match.append(symbol)
            elif name in symbol.name:
                no_exact_match.append(symbol)
        return exact_match + no_exact_match

    def filter(self: SymbolList, value: int | str) -> SymbolList[Symbol]:
        """Filters the symbols according to the specified value.

        If the value is an integer, it is treated as an address.
        If the value is a string, it is treated as a symbol name.

        Args:
            value (int | str): The address or name of the symbol to find.

        Returns:
            SymbolList[Symbol]: The symbols matching the specified value.
        """
        if isinstance(value, int):
            filtered_symbols = self._search_by_address(value)
        elif isinstance(value, str):
            filtered_symbols = self._search_by_name(value)
        else:
            raise TypeError("The value must be an integer or a string.")

        return SymbolList(filtered_symbols, self._maps_source)

    def __getitem__(self: SymbolList, key: str | int) -> SymbolList[Symbol] | Symbol:
        """Returns the symbol with the specified name.

        Args:
            key (str, int): The name of the symbol to return, or the index of the symbol in the list.

        Returns:
            Symbol | SymbolList[Symbol]: The symbol at the specified index, or the SymbolList of symbols with the specified name.
        """
        if not isinstance(key, str):
            return super().__getitem__(key)

        symbols = [symbol for symbol in self if symbol.name == key]
        if not symbols:
            raise KeyError(f"Symbol '{key}' not found.")
        return SymbolList(symbols, self._maps_source)

    def __hash__(self) -> int:
        """Return the hash of the symbol list."""
        return hash(id(self))

    def __eq__(self, other: object) -> bool:
        """Check if the symbol list is equal to another object."""
        return super().__eq__(other)

    def __repr__(self: SymbolList) -> str:
        """Returns the string representation of the SymbolDict without the default factory."""
        return f"SymbolList({super().__repr__()})"

__eq__(other)

Check if the symbol list is equal to another object.

Source code in libdebug/data/symbol_list.py 
105
106
107
def __eq__(self, other: object) -> bool:
    """Check if the symbol list is equal to another object."""
    return super().__eq__(other)

__getitem__(key)

Returns the symbol with the specified name.

Parameters:

Name Type Description Default
key (str, int)

The name of the symbol to return, or the index of the symbol in the list.

 required

Returns:

Type Description
SymbolList[Symbol] | Symbol

Symbol | SymbolList[Symbol]: The symbol at the specified index, or the SymbolList of symbols with the specified name.
Source code in libdebug/data/symbol_list.py 
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def __getitem__(self: SymbolList, key: str | int) -> SymbolList[Symbol] | Symbol:
    """Returns the symbol with the specified name.

    Args:
        key (str, int): The name of the symbol to return, or the index of the symbol in the list.

    Returns:
        Symbol | SymbolList[Symbol]: The symbol at the specified index, or the SymbolList of symbols with the specified name.
    """
    if not isinstance(key, str):
        return super().__getitem__(key)

    symbols = [symbol for symbol in self if symbol.name == key]
    if not symbols:
        raise KeyError(f"Symbol '{key}' not found.")
    return SymbolList(symbols, self._maps_source)

__hash__()

Return the hash of the symbol list.

Source code in libdebug/data/symbol_list.py 
101
102
103
def __hash__(self) -> int:
    """Return the hash of the symbol list."""
    return hash(id(self))

__init__(symbols, maps_source)

Initializes the SymbolDict.

Source code in libdebug/data/symbol_list.py 
20
21
22
23
24
def __init__(self: SymbolList, symbols: list[Symbol], maps_source: InternalDebugger | Snapshot) -> None:
    """Initializes the SymbolDict."""
    super().__init__(symbols)

    self._maps_source = maps_source

__repr__()

Returns the string representation of the SymbolDict without the default factory.

Source code in libdebug/data/symbol_list.py 
109
110
111
def __repr__(self: SymbolList) -> str:
    """Returns the string representation of the SymbolDict without the default factory."""
    return f"SymbolList({super().__repr__()})"

_search_by_address(address)

Searches for a symbol by address.

Parameters:

Name Type Description Default
address int

The address of the symbol to search for.

 required

Returns:

Type Description
list[Symbol]

list[Symbol]: The list of symbols that match the specified address.
Source code in libdebug/data/symbol_list.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def _search_by_address(self: SymbolList, address: int) -> list[Symbol]:
    """Searches for a symbol by address.

    Args:
        address (int): The address of the symbol to search for.

    Returns:
        list[Symbol]: The list of symbols that match the specified address.
    """
    # Find the memory map that contains the address
    if maps := self._maps_source.maps.filter(address):
        address -= maps[0].start
    else:
        raise ValueError(
            f"Address {address:#x} does not belong to any memory map. You must specify an absolute address.",
        )
    return [symbol for symbol in self if symbol.start <= address < symbol.end]

_search_by_name(name)

Searches for a symbol by name.

Parameters:

Name Type Description Default
name str

The name of the symbol to search for.

 required

Returns:

Type Description
list[Symbol]

list[Symbol]: The list of symbols that match the specified name.
Source code in libdebug/data/symbol_list.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
def _search_by_name(self: SymbolList, name: str) -> list[Symbol]:
    """Searches for a symbol by name.

    Args:
        name (str): The name of the symbol to search for.

    Returns:
        list[Symbol]: The list of symbols that match the specified name.
    """
    exact_match = []
    no_exact_match = []
    # We first want to list the symbols that exactly match the name
    for symbol in self:
        if symbol.name == name:
            exact_match.append(symbol)
        elif name in symbol.name:
            no_exact_match.append(symbol)
    return exact_match + no_exact_match

filter(value)

Filters the symbols according to the specified value.

If the value is an integer, it is treated as an address. If the value is a string, it is treated as a symbol name.

Parameters:

Name Type Description Default
value int | str

The address or name of the symbol to find.

 required

Returns:

Type Description
SymbolList[Symbol]

SymbolList[Symbol]: The symbols matching the specified value.
Source code in libdebug/data/symbol_list.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def filter(self: SymbolList, value: int | str) -> SymbolList[Symbol]:
    """Filters the symbols according to the specified value.

    If the value is an integer, it is treated as an address.
    If the value is a string, it is treated as a symbol name.

    Args:
        value (int | str): The address or name of the symbol to find.

    Returns:
        SymbolList[Symbol]: The symbols matching the specified value.
    """
    if isinstance(value, int):
        filtered_symbols = self._search_by_address(value)
    elif isinstance(value, str):
        filtered_symbols = self._search_by_name(value)
    else:
        raise TypeError("The value must be an integer or a string.")

    return SymbolList(filtered_symbols, self._maps_source)