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
112
113
114
115
116
117
118
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 backing file that contains the address
        map_middle = self._maps_source.maps.filter(address)

        if map_middle:
            backing_file_first_map = self._maps_source.maps.filter(map_middle[0].backing_file)[0]
            address -= backing_file_first_map.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
            and symbol.reference_file == map_middle[0].backing_file
        ]

    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 
112
113
114
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 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
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 
108
109
110
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 
116
117
118
def __repr__(self: SymbolList) -> str:
    """Returns the string representation of the SymbolDict without the default factory."""
    return f"SymbolList({super().__repr__()})"

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 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
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)