ionicons-v5-d 0.17.0 (259bf709)
Updated on 25/12/2024, 05:37:07.

Python

lief.dsc.load(*args) → lief.dsc.DyldSharedCache | None
lief.dsc.load(path: os.PathLike, arch: str = '') → lief._lief.dsc.DyldSharedCache | None

Overloaded function.

  1. load(files: collections.abc.Sequence[str]) -> Optional[lief._lief.dsc.DyldSharedCache]

    Load a shared cache from a list of files.

    files = [
  "/tmp/dsc/dyld_shared_cache_arm64e",
  "/tmp/dsc/dyld_shared_cache_arm64e.1"
]
cache = lief.dsc.load(files);

  2. load(path: os.PathLike, arch: str = '') -> Optional[lief._lief.dsc.DyldSharedCache]

    Load a shared cache from the a single file or from a directory specified by the path parameter.

    In the case where multiple architectures are available in the path directory, the arch parameter can be used to define which architecture should be prefered.

    Example:

    // From a directory (split caches)
cache = lief.dsc.load("vision-pro-2.0/");

// From a single cache file
cache = lief.dsc.load("ios-14.2/dyld_shared_cache_arm64");

// From a directory with multiple architectures
cache = lief.dsc.load("macos-12.6/", "x86_64h");

Cache Processing

Warning

If you aim at extracting several libraries from a dyld shared cache, it is highly recommended to enable caching. Otherwise, performances can be impacted.

lief.dsc.enable_cache(*args) → bool
lief.dsc.enable_cache(target_cache_dir: str) → bool

Overloaded function.

  1. enable_cache() -> bool

    Enable globally cache/memoization. One can also leverage this function by setting the environment variable DYLDSC_ENABLE_CACHE to 1

    By default, LIEF will use the directory specified by the environment variable DYLDSC_CACHE_DIR as its cache-root directory:

    DYLDSC_ENABLE_CACHE=1 DYLDSC_CACHE_DIR=/tmp/my_dir python ./my-script.py

    Otherwise, if DYLDSC_CACHE_DIR is not set, LIEF will use the following directory (in this priority):

    1. System or user cache directory

    • macOS: DARWIN_USER_TEMP_DIR / DARWIN_USER_CACHE_DIR + /dyld_shared_cache

    • Linux: ${XDG_CACHE_HOME}/dyld_shared_cache

    • Windows: %LOCALAPPDATA%\dyld_shared_cache

    1. Home directory

    • macOS/Linux: $HOME/.dyld_shared_cache

    • Windows: %USERPROFILE%\.dyld_shared_cache

    See lief.dsc.DyldSharedCache.enable_caching() for a finer granularity

  2. enable_cache(target_cache_dir: str) -> bool

    Same behavior as the other enable_cache() function but using a user-provided cache directory instead of an inferred one.

DyldSharedCache

class lief.dsc.DyldSharedCache

Bases: object

This class represents a dyld shared cache file.

class ARCH(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Architecture supported by the dyld shared cache

ARM64 = 7
ARM64E = 8
ARMV5 = 4
ARMV6 = 5
ARMV7 = 6
I386 = 1
UNKNOWN = 0
X86_64 = 2
X86_64H = 3
class PLATFORM(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Platforms supported by the dyld shared cache

ANY = 4294967295
BRIDGEOS = 5
DRIVERKIT = 10
FIRMWARE = 13
IOS = 2
IOSMAC = 6
IOS_SIMULATOR = 7
MACOS = 1
SEPOS = 14
TVOS = 3
TVOS_SIMULATOR = 8
UNKNOWN = 0
VISIONOS = 11
VISIONOS_SIMULATOR = 12
WATCHOS = 4
WATCHOS_SIMULATOR = 9
class VERSION(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

DYLD_1042_1 = 8
DYLD_1231_3 = 9
DYLD_195_5 = 2
DYLD_239_3 = 3
DYLD_360_14 = 4
DYLD_421_1 = 5
DYLD_832_7_1 = 6
DYLD_940 = 7
DYLD_95_3 = 1
UNKNOWN = 0
UNRELEASED = 10
property arch → lief.dsc.DyldSharedCache.ARCH

Architecture targeted by this cache

property arch_name → str

Name of the architecture targeted by this cache (x86_64h)

cache_for_address(self, address: int) → lief.dsc.DyldSharedCache | None

Find the sub-DyldSharedCache that wraps the given virtual address

disassemble(self, arg: int) → Iterator[lief.assembly.Instruction | None]

Disassemble instructions at the provided virtual address.

This function returns an iterator over lief.assembly.Instruction.

enable_caching(self, target_dir: str) → None

When enabled, this function allows to record and to keep in cache, dyld shared cache information that are costly to access.

For instance, GOT symbols, rebases information, stub symbols, …

It is highly recommended to enable this function when processing a dyld shared cache several times or when extracting a large number of lief.dsc.Dylib with enhanced extraction options (e.g. lief.dsc.Dylib.extract_opt_t.fix_branches)

One can enable caching by calling this function:

dyld_cache = lief.dsc.load("macos-15.0.1/");
dyld_cache.enable_caching("~/.cache/lief-dsc");

One can also enable this cache optimization globally using the function: lief.dsc.enable_cache() or by setting the environment variable DYLDSC_ENABLE_CACHE to 1.

property filename → str

Filename of the dyld shared file associated with this object.

For instance: dyld_shared_cache_arm64e, dyld_shared_cache_arm64e.62.dyldlinkedit

property filepath → str

Full path to the original dyld shared cache file associated with object (e.g. /cache/visionos/dyld_shared_cache_arm64e.42)

find_lib_from_name(self, name: str) → lief.dsc.Dylib | None

Find the Dylib whose filename of lief.dsc.Dylib.path matches the provided name.

If multiple libraries have the same name (but with a different path), the first one matching the provided name is returned.

find_lib_from_path(self, path: str) → lief.dsc.Dylib | None

Find the Dylib whose lief.dsc.Dylib.path matches the provided path.

find_lib_from_va(self, virtual_address: int) → lief.dsc.Dylib | None

Find the lief.dsc.Dylib that encompasses the given virtual address. It returns None if a Dylib can’t be found.

find_subcache(self, filename: str) → lief.dsc.DyldSharedCache | None

Try to find the DyldSharedCache associated with the filename given in the first parameter.

flush_cache(self) → None

Flush internal information into the on-disk cache (see: enable_caching())

from_files(files: collections.abc.Sequence[str]) → lief.dsc.DyldSharedCache | None = <nanobind.nb_func object>
from_path(path: str, arch: str) → lief.dsc.DyldSharedCache | None = <nanobind.nb_func object>
get_content_from_va(self, addr: int, size: int) → bytes

Return the content at the specified virtual address

property has_subcaches → bool

True if the subcaches are associated with this cache

property libraries → collections.abc.Sequence[lief.dsc.Dylib | None]

Return a list-like of the Dylib embedded in this dyld shared cache

property load_address → int

Based address of this cache

property main_cache → lief.dsc.DyldSharedCache | None

Return the principal dyld shared cache in the case of multiple subcaches

property mapping_info → collections.abc.Sequence[lief.dsc.MappingInfo | None]

Return a list-like of the MappingInfo embedded in this dyld shared cache

property platform → lief.dsc.DyldSharedCache.PLATFORM

Platform targeted by this cache (e.g. vision-os)

property subcaches → collections.abc.Sequence[lief.dsc.SubCache | None]

Return a list-like of SubCache embedded in this (main) dyld shared cache

va_to_offset(self, virtual_address: int) → int | lief.lief_errors

Convert the given virtual address into an offset.

Warning

If the shared cache contains multiple subcaches, this function needs to be called on the targeted subcache. See cache_for_address() to find the associated subcache.

property version → lief.dsc.DyldSharedCache.VERSION

Version of dyld used by this cache

Dylib

class lief.dsc.Dylib

Bases: object

This class represents a library embedded in a dyld shared cache. It mirrors the original dyld_cache_image_info structure.

property address → int

In-memory address of the library

class extract_opt_t(self)

Bases: object

This structure is used to tweak the extraction process while calling lief.dsc.Dylib.get(). These options allow to deoptimize the dylib and get an accurate representation of the origin Mach-O binary.

property create_dyld_chained_fixup_cmd → bool

Whether the LC_DYLD_CHAINED_FIXUPS command should be (re)created.

If this value is not set, LIEF will add the command only if it’s meaningful regarding the other options

property fix_branches → bool

Fix call instructions that target addresses outside the current dylib virtual space.

Warning

Enabling this option can have a significant impact on the performances. Make sure to enable the internal cache mechanism: lief.dsc.enable_cache() or lief.dsc.DyldSharedCache.enable_caching()

property fix_memory → bool

Fix memory accesses performed outside the dylib’s virtual space

Warning

Enabling this option can have a significant impact on the performances. Make sure to enable the internal cache mechanism: lief.dsc.enable_cache() or lief.dsc.DyldSharedCache.enable_caching()

property fix_objc → bool

Fix Objective-C information

Warning

Enabling this option can have a significant impact on the performances. Make sure to enable the internal cache mechanism: lief.dsc.enable_cache() or lief.dsc.DyldSharedCache.enable_caching()

property fix_relocations → bool

Recover and fix relocations

Warning

Enabling this option can have a significant impact on the performances. Make sure to enable the internal cache mechanism: lief.dsc.enable_cache() or lief.dsc.DyldSharedCache.enable_caching()

property pack → bool

Whether the segment’s offsets should be packed to avoid an in-memory size while writing back the binary.

Note

This option does not have an impact on the performances

get(self, opt: lief.dsc.Dylib.extract_opt_t) → lief.MachO.Binary | None

Get a lief.MachO.Binary representation for this Dylib.

One can use this function to write back the Mach-O binary on the disk:

dyld_cache: lief.dsc.DyldSharedCache = ...
dyld_cache.libraries[10].get().write("libsystem.dylib")
property inode → int

File serial number matching stat.st_ino or 0

Note that for shared cache targeting iOS, this value can hold a hash of the path (if modtime is set to 0)

property modtime → int

Modification time of the library matching stat.st_mtime, or 0

property padding → int

Padding alignment value (should be 0)

property path → str

Original path of the library (e.g. /usr/lib/libcryptex.dylib)

MappingInfo

class lief.dsc.MappingInfo

Bases: object

This class represents a dyld_cache_mapping_info entry.

It provides information about the relationshiop between on-disk shared cache and in-memory shared cache.

property address → int

The in-memory address where this dyld shared cache region is mapped

property end_address → int

End virtual address of the region

property file_offset → int

On-disk file offset

property init_prot → int

Initial memory protection

property max_prot → int

Max memory protection

property size → int

Size of the region being mapped

SubCache

class lief.dsc.SubCache

Bases: object

This class represents a subcache in the case of large/split dyld shared cache.

It mirror (and abstracts) the original dyld_subcache_entry / dyld_subcache_entry_v1

property cache → lief.dsc.DyldSharedCache | None

The associated DyldSharedCache object for this subcache

property suffix → str

The file name suffix of the subCache file (e.g. .25.data, .03.development)

property uuid → list[int]

The uuid of the subcache file

property vm_offset → int

The offset of this subcache from the main cache base address