Skip to content

libdebug.snapshots.memory.memory_map_snapshot_list

MemoryMapSnapshotList

Bases: list[MemoryMapSnapshot]

A list of memory map snapshot from the target process.

Source code in libdebug/snapshots/memory/memory_map_snapshot_list.py
class MemoryMapSnapshotList(list[MemoryMapSnapshot]):
    """A list of memory map snapshot from the target process."""

    def __init__(
        self: MemoryMapSnapshotList,
        memory_maps: list[MemoryMapSnapshot],
        process_name: str,
        full_process_path: str,
    ) -> None:
        """Initializes the MemoryMapSnapshotList."""
        super().__init__(memory_maps)
        self._process_full_path = full_process_path
        self._process_name = process_name

    def _search_by_address(self: MemoryMapSnapshotList, address: int) -> list[MemoryMapSnapshot]:
        """Searches for a memory map by address.

        Args:
            address (int): The address to search for.

        Returns:
            list[MemoryMapSnapshot]: The memory map matching the specified address.
        """
        for vmap in self:
            if vmap.start <= address < vmap.end:
                return [vmap]
        return []

    def _search_by_backing_file(self: MemoryMapSnapshotList, backing_file: str) -> list[MemoryMapSnapshot]:
        """Searches for a memory map by backing file.

        Args:
            backing_file (str): The backing file to search for.

        Returns:
            list[MemoryMapSnapshot]: The memory map matching the specified backing file.
        """
        if backing_file in ["binary", self._process_name]:
            backing_file = self._process_full_path

        filtered_maps = []
        unique_files = set()

        for vmap in self:
            if backing_file in vmap.backing_file:
                filtered_maps.append(vmap)
                unique_files.add(vmap.backing_file)

        if len(unique_files) > 1:
            liblog.warning(
                f"The substring {backing_file} is present in multiple, different backing files. The address resolution cannot be accurate. The matching backing files are: {', '.join(unique_files)}.",
            )

        return filtered_maps

    def filter(self: MemoryMapSnapshotList, value: int | str) -> MemoryMapSnapshotList[MemoryMapSnapshot]:
        """Filters the memory maps 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 backing file.

        Args:
            value (int | str): The value to search for.

        Returns:
            MemoryMapSnapshotList[MemoryMapSnapshot]: The memory map snapshots matching the specified value.
        """
        if isinstance(value, int):
            filtered_maps = self._search_by_address(value)
        elif isinstance(value, str):
            filtered_maps = self._search_by_backing_file(value)
        else:
            raise TypeError("The value must be an integer or a string.")

        return MemoryMapSnapshotList(filtered_maps, self._process_name, self._process_full_path)

__init__(memory_maps, process_name, full_process_path)

Initializes the MemoryMapSnapshotList.

Source code in libdebug/snapshots/memory/memory_map_snapshot_list.py
def __init__(
    self: MemoryMapSnapshotList,
    memory_maps: list[MemoryMapSnapshot],
    process_name: str,
    full_process_path: str,
) -> None:
    """Initializes the MemoryMapSnapshotList."""
    super().__init__(memory_maps)
    self._process_full_path = full_process_path
    self._process_name = process_name

_search_by_address(address)

Searches for a memory map by address.

Parameters:

Name Type Description Default
address int

The address to search for.

required

Returns:

Type Description
list[MemoryMapSnapshot]

list[MemoryMapSnapshot]: The memory map matching the specified address.

Source code in libdebug/snapshots/memory/memory_map_snapshot_list.py
def _search_by_address(self: MemoryMapSnapshotList, address: int) -> list[MemoryMapSnapshot]:
    """Searches for a memory map by address.

    Args:
        address (int): The address to search for.

    Returns:
        list[MemoryMapSnapshot]: The memory map matching the specified address.
    """
    for vmap in self:
        if vmap.start <= address < vmap.end:
            return [vmap]
    return []

_search_by_backing_file(backing_file)

Searches for a memory map by backing file.

Parameters:

Name Type Description Default
backing_file str

The backing file to search for.

required

Returns:

Type Description
list[MemoryMapSnapshot]

list[MemoryMapSnapshot]: The memory map matching the specified backing file.

Source code in libdebug/snapshots/memory/memory_map_snapshot_list.py
def _search_by_backing_file(self: MemoryMapSnapshotList, backing_file: str) -> list[MemoryMapSnapshot]:
    """Searches for a memory map by backing file.

    Args:
        backing_file (str): The backing file to search for.

    Returns:
        list[MemoryMapSnapshot]: The memory map matching the specified backing file.
    """
    if backing_file in ["binary", self._process_name]:
        backing_file = self._process_full_path

    filtered_maps = []
    unique_files = set()

    for vmap in self:
        if backing_file in vmap.backing_file:
            filtered_maps.append(vmap)
            unique_files.add(vmap.backing_file)

    if len(unique_files) > 1:
        liblog.warning(
            f"The substring {backing_file} is present in multiple, different backing files. The address resolution cannot be accurate. The matching backing files are: {', '.join(unique_files)}.",
        )

    return filtered_maps

filter(value)

Filters the memory maps 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 backing file.

Parameters:

Name Type Description Default
value int | str

The value to search for.

required

Returns:

Type Description
MemoryMapSnapshotList[MemoryMapSnapshot]

MemoryMapSnapshotList[MemoryMapSnapshot]: The memory map snapshots matching the specified value.

Source code in libdebug/snapshots/memory/memory_map_snapshot_list.py
def filter(self: MemoryMapSnapshotList, value: int | str) -> MemoryMapSnapshotList[MemoryMapSnapshot]:
    """Filters the memory maps 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 backing file.

    Args:
        value (int | str): The value to search for.

    Returns:
        MemoryMapSnapshotList[MemoryMapSnapshot]: The memory map snapshots matching the specified value.
    """
    if isinstance(value, int):
        filtered_maps = self._search_by_address(value)
    elif isinstance(value, str):
        filtered_maps = self._search_by_backing_file(value)
    else:
        raise TypeError("The value must be an integer or a string.")

    return MemoryMapSnapshotList(filtered_maps, self._process_name, self._process_full_path)