### Install PySquashfsImage using pip

Source: https://github.com/matteomattei/pysquashfsimage/blob/master/docs/getting_started.md

Use this command to install the library with pip, the preferred package installer for Python.

```bash
sudo pip install PySquashfsImage
```

--------------------------------

### Install PySquashfsImage using easy_install

Source: https://github.com/matteomattei/pysquashfsimage/blob/master/docs/getting_started.md

An alternative installation method using easy_install.

```bash
sudo easy_install PySquashfsImage
```

--------------------------------

### Example: List only directories recursively

Source: https://github.com/matteomattei/pysquashfsimage/blob/master/README.md

Demonstrates using the `pysquashfs list` command to recursively list only directories within a squashfs image. This is similar to `unsquashfs -ll -full`.

```bash
$ pysquashfs list myimage.img -r -t d
drwxrwxrwx 1049/1049               468 2018-10-10 08:14:16 /bin
drwxrwxrwx 1049/1049                 3 2021-05-14 18:46:17 /dev
drwxrwxrwx 1049/1049               869 2019-11-12 09:31:30 /etc
drwxrwxrwx 1049/1049                 3 2021-05-14 18:46:17 /home
drwxrwxrwx 1049/1049               406 2017-12-11 08:14:16 /lib
drwxrwxrwx 1049/1049                98 2021-05-14 18:46:17 /mnt
drwxrwxrwx 1049/1049                 3 2021-05-14 15:12:17 /proc
drwxrwxrwx 1049/1049                 3 2021-05-14 15:12:17 /root
drwxrwxrwx 1049/1049               690 2021-05-14 12:11:44 /sbin
drwxrwxrwx 1049/1049                 3 2021-05-14 15:12:17 /sys
drwxrwxrwx 1049/1049                 3 2021-05-14 18:46:17 /tmp
drwxrwxrwx 1049/1049               364 2021-05-14 18:46:17 /usr
drwxrwxrwx 1049/1049                60 2018-11-09 05:38:43 /var
13 file(s) found
```

--------------------------------

### Print non-directory entries from bytes

Source: https://github.com/matteomattei/pysquashfsimage/blob/master/README.md

Create a SquashFsImage object from bytes read from a file. This example filters and prints paths of entries that are not directories.

```python
from PySquashfsImage import SquashFsImage

with open('/path/to/my/image.img', "rb") as f:
    imgbytes = f.read()

# Create an image from bytes.
with SquashFsImage.from_bytes(imgbytes) as image:
    for item in image:
        if not item.is_dir:
            print(item.path)
```

--------------------------------

### Show Help for pysquashfs extract

Source: https://github.com/matteomattei/pysquashfsimage/blob/master/README.md

Displays the help message for the 'extract' command, detailing its arguments and options. Use this to understand available parameters for extracting files.

```bash
$ pysquashfs extract -h
usage: pysquashfs extract [-h] [-o OFFSET] [-d DEST] [-p PATH] [-f] [-q] file

Extract files from the file system

positional arguments:
  file                        squashfs filesystem

optional arguments:
  -h, --help                  show this help message and exit
  -o OFFSET, --offset OFFSET  absolute position of file system's start. Default: 0
  -d DEST, --dest DEST        directory that will contain the extracted file(s). If it doesn't exist it will be created. Default: current directory
  -p PATH, --path PATH        absolute path of directory or file to extract. Default: '/'
  -f, --force                 overwrite files that already exist. Default: False
  -q, --quiet                 don't print extraction status. Default: False
```

--------------------------------

### Show Help for pysquashfs scan

Source: https://github.com/matteomattei/pysquashfsimage/blob/master/README.md

Displays the help message for the 'scan' command, outlining its arguments and options. Use this to understand how to find and display superblocks within a squashfs file.

```bash
$ pysquashfs scan -h
usage: pysquashfs scan [-h] [--utc] [--showtz] file

Find and show all the superblocks that can be found in a file

positional arguments:
  file        squashfs filesystem

optional arguments:
  -h, --help  show this help message and exit
  --utc       use UTC rather than local time zone when displaying time. Default: False
  --showtz    show UTC offset when displaying time. Default: False
```

--------------------------------

### Directory.riter()

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Recursively iterates over a directory, yielding the directory itself and all its descendants in depth-first order.

```APIDOC
## Directory.riter()

### Description
Yields the directory itself followed by all descendants (files and subdirectories) in depth-first order.

### Method
`riter()`

### Parameters
None

### Request Example
```python
from PySquashfsImage import SquashFsImage

with SquashFsImage.from_file('image.img') as image:
    # Count all regular files
    regular_files = [f for f in image.root.riter() if f.is_file]
    print(f"Total regular files: {len(regular_files)}")

    # Find all symlinks
    symlinks = [f for f in image if f.is_symlink]
    for lnk in symlinks:
        print(f"{lnk.path} -> {lnk.readlink()}")

    # Iterate a specific subdirectory recursively
    usr = image.select('/usr')
    if usr:
        for entry in usr.riter():
            print(entry.path, entry.filemode)
```

### Response
- Returns: `generator` - Yields file system entries (files, directories, symlinks, etc.) recursively.
```

--------------------------------

### pysquashfs list command usage

Source: https://github.com/matteomattei/pysquashfsimage/blob/master/README.md

Display the help message for the `pysquashfs list` command, which lists the contents of a squashfs filesystem. It supports filtering by path and type, recursive listing, and timezone options.

```bash
$ pysquashfs list -h
usage: pysquashfs list [-h] [-o OFFSET] [--utc] [--showtz] [-p PATH] [-r] [-t TYPE [TYPE ...]] file

List the contents of the file system

positional arguments:
  file                        squashfs filesystem

optional arguments:
  -h, --help                  show this help message and exit
  -o OFFSET, --offset OFFSET  absolute position of file system's start. Default: 0
  --utc                       use UTC rather than local time zone when displaying time. Default: False
  --showtz                    show UTC offset when displaying time. Default: False
  -p PATH, --path PATH        absolute path of directory or file to list. Default: '/'
  -r, --recursive             whether to list recursively. For the root directory the value is inverted. Default: False
  -t TYPE [TYPE ...], --type TYPE [TYPE ...]
                              when listing a directory, filter by file type with f, d, l, p, s, b, c
```

--------------------------------

### SquashFsImage.from_file(path, offset=0)

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Opens a squashfs image from a file path. An optional offset can be provided to specify the superblock's position within the file, which is useful for embedded filesystems.

```APIDOC
## SquashFsImage.from_file(path, offset=0)

### Description
Opens a squashfs image from a file path. The optional `offset` parameter specifies the byte position of the squashfs superblock within the file (useful for firmware blobs where the filesystem is embedded mid-file).

### Method
`SquashFsImage.from_file`

### Parameters
#### Path Parameters
- **path** (string) - Required - The file path to the squashfs image.
- **offset** (integer) - Optional - The byte offset to the superblock. Defaults to 0.

### Request Example
```python
from PySquashfsImage import SquashFsImage

with SquashFsImage.from_file('/path/to/firmware.img') as image:
    for entry in image:
        print(entry.path, entry.filemode, entry.uid, entry.gid)

with SquashFsImage.from_file('firmware.bin', offset=161843) as image:
    print("Filesystem size:", image.size, "bytes")
    print("Root children:", list(image.root.children.keys()))
```

### Response
#### Success Response (SquashFsImage object)
- **image** (SquashFsImage) - An object representing the opened squashfs image, usable as a context manager.

#### Response Example
(See Request Example for usage)
```

--------------------------------

### Open SquashFS Image from File Path

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Opens a squashfs image from a file path. Use a context manager for proper resource handling. An optional offset can be provided for embedded filesystems.

```python
from PySquashfsImage import SquashFsImage

# Open and iterate all entries (recommended: use context manager)
with SquashFsImage.from_file('/path/to/firmware.img') as image:
    for entry in image:
        print(entry.path, entry.filemode, entry.uid, entry.gid)
# Output:
# / drwxr-xr-x 0 0
# /bin drwxrwxrwx 1049 1049
# /bin/sh lrwxrwxrwx 1049 1049
# /etc/passwd -rw-r--r-- 0 0

# Open with a byte offset (e.g., squashfs starts at byte 161843 inside a firmware)
with SquashFsImage.from_file('firmware.bin', offset=161843) as image:
    print("Filesystem size:", image.size, "bytes")
    print("Root children:", list(image.root.children.keys()))
```

--------------------------------

### List Filesystem Contents with pysquashfs

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Lists entries in a squashfs image. Supports filtering by file type, recursive listing, and timezone control. Use for inspecting image contents without extraction.

```bash
pysquashfs list myimage.img -r -t d
```

```bash
pysquashfs list myimage.img -p /etc -t f
```

```bash
pysquashfs list myimage.img --utc --showtz
```

```bash
pysquashfs list firmware.bin -o 161843
```

--------------------------------

### Select File or Directory by Path

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Retrieves a file or directory object at the specified absolute path. Returns None if the path does not exist. Supports reading file content and symlink targets.

```python
from PySquashfsImage import SquashFsImage

with SquashFsImage.from_file('image.img') as image:
    # Select a directory
    bin_dir = image.select('/bin')
    if bin_dir and bin_dir.is_dir:
        print("Contents of /bin:")
        for child in bin_dir:
            print(" ", child.name, child.filemode)

    # Select a specific file
    busybox = image.select('/bin/busybox')
    if busybox and busybox.is_file:
        print("busybox size:", busybox.size)
        # Read entire content
        data = busybox.read_bytes()
        print("ELF magic:", data[:4])           # b'\x7fELF'

    # Select a symlink
    sh = image.select('/bin/sh')
    if sh and sh.is_symlink:
        print("/bin/sh ->", sh.readlink())      # busybox
```

--------------------------------

### SquashFsImage(fd, offset=0, closefd=True)

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Constructs a SquashFsImage object from a file-like object. This method allows using any object that supports `read()` and `seek()`, such as file handles or network sockets.

```APIDOC
## SquashFsImage(fd, offset=0, closefd=True)

### Description
Construct directly from any file-like object that supports `read()` and `seek()`. Set `closefd=False` to prevent the image from closing the file descriptor on exit.

### Method
`SquashFsImage` constructor

### Parameters
#### Path Parameters
- **fd** (file-like object) - Required - The file-like object to read the image from.
- **offset** (integer) - Optional - The byte offset to the superblock. Defaults to 0.
- **closefd** (boolean) - Optional - Whether to close the file descriptor when the image is closed. Defaults to True.

### Request Example
```python
from PySquashfsImage import SquashFsImage

with open('image.img', 'rb') as f:
    with SquashFsImage(f, closefd=False) as image:
        print("Inodes:", image.sblk.inodes)
        print("Compression:", image.sblk.compression)
        print("Block size:", image.sblk.block_size)
```

### Response
#### Success Response (SquashFsImage object)
- **image** (SquashFsImage) - An object representing the opened squashfs image, usable as a context manager.

#### Response Example
(See Request Example for usage)
```

--------------------------------

### List all elements in a squashfs image

Source: https://github.com/matteomattei/pysquashfsimage/blob/master/README.md

Iterate through all items in a squashfs image and print their names. Ensure the image file is closed after use.

```python
from PySquashfsImage import SquashFsImage

image = SquashFsImage.from_file('/path/to/my/image.img')
for item in image:
    print(item.name)
image.close()
```

--------------------------------

### extract_file(file, dest, force=False, quiet=True)

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Extracts a single file to the local filesystem, preserving metadata. Supports overwriting with `force=True`.

```APIDOC
## extract_file(file, dest, force=False, quiet=True)

### Description
Extracts a single file (any type: regular file, symlink, device, FIFO, socket) to the local filesystem, preserving timestamps, permissions, ownership (if root), and hard links. Pass `force=True` to overwrite existing files.

### Method
`extract_file(file, dest, force=False, quiet=True)`

### Parameters
- **file**: The file object or path to extract.
- **dest**: The destination path on the local filesystem.
- **force** (bool, optional): If `True`, overwrite existing files. Defaults to `False`.
- **quiet** (bool, optional): If `True`, suppress output. Defaults to `True`.

### Request Example
```python
from PySquashfsImage import SquashFsImage
from PySquashfsImage.extract import extract_file

with SquashFsImage.from_file('image.img') as image:
    target = image.find('busybox')
    if target and target.is_file:
        try:
            extract_file(target, '/tmp/busybox', force=True, quiet=False)
            # Output: extract /bin/busybox to /tmp/busybox
        except FileExistsError:
            print("File already exists; use force=True to overwrite")

    # Extract a symlink
    sh = image.select('/bin/sh')
    if sh and sh.is_symlink:
        extract_file(sh, '/tmp/sh')
        # Creates a symlink: /tmp/sh -> busybox
```

### Response
None. Raises `FileExistsError` if `force` is `False` and the destination exists.
```

--------------------------------

### Extract a Directory from Squashfs Image

Source: https://github.com/matteomattei/pysquashfsimage/blob/master/README.md

Extracts a specific directory (e.g., /bin) from a squashfs image file to a specified destination directory. Ensure the destination directory exists or will be created.

```bash
$ pysquashfs extract myimage.img -p /bin -d /tmp
```

--------------------------------

### Extract Files from Squashfs Image with pysquashfs

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Extracts files or directories from a squashfs image to the local filesystem. Preserves timestamps, permissions, symlinks, and hard links. Use for retrieving specific files or entire directory trees.

```bash
pysquashfs extract myimage.img
```

```bash
pysquashfs extract myimage.img -p /bin -d /tmp
```

```bash
pysquashfs extract myimage.img -p /etc/passwd -d /tmp -f -q
```

```bash
pysquashfs extract firmware.bin -o 161843 -d /tmp/firmware_root
```

--------------------------------

### Extract Single File with Metadata

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Extracts a single file (regular file, symlink, device, FIFO, socket) to the local filesystem, preserving metadata like timestamps, permissions, and ownership. Use `force=True` to overwrite existing files.

```python
from PySquashfsImage import SquashFsImage
from PySquashfsImage.extract import extract_file

with SquashFsImage.from_file('image.img') as image:
    target = image.find('busybox')
    if target and target.is_file:
        try:
            extract_file(target, '/tmp/busybox', force=True, quiet=False)
            # Output: extract /bin/busybox to /tmp/busybox
        except FileExistsError:
            print("File already exists; use force=True to overwrite")

    # Extract a symlink
    sh = image.select('/bin/sh')
    if sh and sh.is_symlink:
        extract_file(sh, '/tmp/sh')
        # Creates a symlink: /tmp/sh -> busybox
```

--------------------------------

### Open SquashFS Image from File-like Object

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Constructs a SquashFsImage directly from any file-like object. Set `closefd=False` to prevent the image from closing the file descriptor upon exit.

```python
from PySquashfsImage import SquashFsImage

with open('image.img', 'rb') as f:
    with SquashFsImage(f, closefd=False) as image:
        print("Inodes:", image.sblk.inodes)
        print("Compression:", image.sblk.compression)
        print("Block size:", image.sblk.block_size)
```

--------------------------------

### Print absolute paths of all entries

Source: https://github.com/matteomattei/pysquashfsimage/blob/master/README.md

Use a context manager for safe handling of the image file. This snippet prints the absolute path of each entry within the image.

```python
from PySquashfsImage import SquashFsImage

# Use with a context manager (recommended).
with SquashFsImage.from_file('/path/to/my/image.img') as image:
    for file in image:
        print(file.path)
```

--------------------------------

### extract_dir(directory, dest, force=False, quiet=True)

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Recursively extracts an entire directory tree to the local filesystem, preserving metadata and hard links.

```APIDOC
## extract_dir(directory, dest, force=False, quiet=True)

### Description
Recursively extracts a directory and all its contents to the local filesystem, preserving file types, metadata, and hard links.

### Method
`extract_dir(directory, dest, force=False, quiet=True)`

### Parameters
- **directory**: The directory object or path to extract.
- **dest**: The destination path on the local filesystem.
- **force** (bool, optional): If `True`, overwrite existing files. Defaults to `False`.
- **quiet** (bool, optional): If `True`, suppress output. Defaults to `True`.

### Request Example
```python
from PySquashfsImage import SquashFsImage
from PySquashfsImage.extract import extract_dir

with SquashFsImage.from_file('image.img') as image:
    etc = image.select('/etc')
    if etc and etc.is_dir:
        extract_dir(etc, '/tmp/extracted_etc', force=True, quiet=False)
        # Output:
        # extract /etc to /tmp/extracted_etc
        # extract /etc/passwd to /tmp/extracted_etc/passwd
        # extract /etc/group to /tmp/extracted_etc/group
        # ...

    # Extract full filesystem
    root = image.root
    extract_dir(root, '/tmp/squashfs-root', force=False)
```

### Response
None.
```

--------------------------------

### image.select(path)

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Retrieves a file or directory object at the specified absolute path within the squashfs image. Returns None if the path does not exist.

```APIDOC
## image.select(path)

### Description
Returns the file or directory object at the given absolute path, or `None` if the path does not exist. Supports both files and directories.

### Method
`select` method of a `SquashFsImage` object

### Parameters
#### Path Parameters
- **path** (string) - Required - The absolute path to the file or directory within the squashfs image.

### Request Example
```python
from PySquashfsImage import SquashFsImage

with SquashFsImage.from_file('image.img') as image:
    # Select a directory
    bin_dir = image.select('/bin')
    if bin_dir and bin_dir.is_dir:
        print("Contents of /bin:")
        for child in bin_dir:
            print(" ", child.name, child.filemode)

    # Select a specific file
    busybox = image.select('/bin/busybox')
    if busybox and busybox.is_file:
        print("busybox size:", busybox.size)
        data = busybox.read_bytes()
        print("ELF magic:", data[:4])           # b'\x7fELF'

    # Select a symlink
    sh = image.select('/bin/sh')
    if sh and sh.is_symlink:
        print("/bin/sh ->", sh.readlink())      # busybox
```

### Response
#### Success Response (File object or None)
- **file object** (RegularFile, Directory, Symlink, etc.) - The object representing the file or directory at the specified path.
- **None** - If the path does not exist within the image.

#### Response Example
(See Request Example for usage)
```

--------------------------------

### Find File by Name in SquashFS Image

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Recursively searches the filesystem tree for a file matching the given name. Returns the file object or None if not found. Provides access to file metadata and content.

```python
from PySquashfsImage import SquashFsImage

with SquashFsImage.from_file('image.img') as image:
    passwd = image.find('passwd')
    if passwd is not None:
        print("Found:", passwd.path)           # /etc/passwd
        print("Size:", passwd.size, "bytes")
        print("Mode:", passwd.filemode)         # -rw-r--r--
        print("Owner:", passwd.uid, passwd.gid)
        content = passwd.read_bytes()
        print(content.decode('utf-8'))
    else:
        print("File not found")
```

--------------------------------

### Open SquashFS Image from Bytes

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Creates a SquashFsImage from a bytes object. This is useful when the image data is already in memory or received over a network.

```python
from PySquashfsImage import SquashFsImage

with open('/path/to/image.img', 'rb') as f:
    raw = f.read()

with SquashFsImage.from_bytes(raw) as image:
    for item in image:
        if not item.is_dir:
            print(item.path)
# Output:
# /bin/busybox
# /bin/sh -> busybox  (symlink)
# /etc/passwd
```

--------------------------------

### Scan Squashfs Image for Superblocks with pysquashfs

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Scans a file for all squashfs 4.0 superblocks and prints their metadata. Use for identifying squashfs image locations within a larger file or for inspecting image properties.

```bash
pysquashfs scan myimage.img
```

```bash
pysquashfs scan firmware.bin --utc --showtz
```

--------------------------------

### Save a file's content from a squashfs image

Source: https://github.com/matteomattei/pysquashfsimage/blob/master/README.md

Find a specific file by name and save its content to a local file. For large files, iterate over content blocks. The `extract_file` function can also be used to preserve metadata.

```python
from PySquashfsImage import SquashFsImage
from PySquashfsImage.extract import extract_file

with SquashFsImage.from_file('/path/to/my/image.img') as image:
    myfile = image.find('myfilename')
    if myfile is not None:
        with open('/tmp/' + myfile.name, 'wb') as f:
            print('Saving original ' + myfile.path + ' in /tmp/' + myfile.name)
            f.write(myfile.read_bytes())

    # If the file is large it's preferable to iterate over its content.
    hugefile = image.select("/hugedir/myhugefile.big")
    with open("myhugefile.big", "wb") as f:
        for block in hugefile.iter_bytes():
            f.write(block)

    # Or use extract_file(), which preserves the file's metadata (except extended attributes).
    extract_file(myfile, "myextractedfile")
```

--------------------------------

### Save a directory's content from a squashfs image

Source: https://github.com/matteomattei/pysquashfsimage/blob/master/README.md

Select a directory from the squashfs image and extract its entire content to a specified local path using `extract_dir`. This function also handles file metadata.

```python
from PySquashfsImage import SquashFsImage
from PySquashfsImage.extract import extract_dir

with SquashFsImage.from_file('/path/to/my/image.img') as image:
    mydir = image.select("/mydir")
    if mydir is not None:
        # Metadata is handled the same way as with extract_file().
        extract_dir(mydir, "/tmp/mydir")
```

--------------------------------

### image.find(filename)

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Recursively searches the entire filesystem tree for the first file matching the given filename. Returns the file object if found, otherwise returns None.

```APIDOC
## image.find(filename)

### Description
Recursively searches the entire filesystem tree for the first file whose name matches `filename`. Returns the file object or `None` if not found.

### Method
`find` method of a `SquashFsImage` object

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name of the file to search for.

### Request Example
```python
from PySquashfsImage import SquashFsImage

with SquashFsImage.from_file('image.img') as image:
    passwd = image.find('passwd')
    if passwd is not None:
        print("Found:", passwd.path)           # /etc/passwd
        print("Size:", passwd.size, "bytes")
        print("Mode:", passwd.filemode)         # -rw-r--r--
        print("Owner:", passwd.uid, passwd.gid)
        content = passwd.read_bytes()
        print(content.decode('utf-8'))
    else:
        print("File not found")
```

### Response
#### Success Response (File object or None)
- **file object** (RegularFile, Directory, Symlink, etc.) - The first matching file object found.
- **None** - If no file with the given name is found.

#### Response Example
(See Request Example for usage)
```

--------------------------------

### find_superblocks(file_or_bytes)

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Scans a binary blob or file for squashfs 4.0 superblocks, returning their offsets and metadata.

```APIDOC
## find_superblocks(file_or_bytes)

### Description
Scans a file path, file-like object, or `bytes` for squashfs 4.0 superblocks and returns a list of dicts, one per superblock found, each including the byte `offset`. Useful for firmware images that embed one or more squashfs filesystems.

### Method
`find_superblocks(file_or_bytes)`

### Parameters
- **file_or_bytes**: A file path (string), file-like object, or `bytes` object to scan.

### Request Example
```python
from PySquashfsImage.util import find_superblocks
from PySquashfsImage import SquashFsImage

# Scan a firmware image for embedded squashfs filesystems
superblocks = find_superblocks('firmware.bin')
for sb in superblocks:
    print(f"Superblock at offset {sb['offset']}:")
    print(f"  Compression: {sb['compression']}")
    print(f"  Size: {sb['bytes_used']} bytes")
    print(f"  Inodes: {sb['inodes']}")

# Then open each one
for sb in superblocks:
    with SquashFsImage.from_file('firmware.bin', offset=sb['offset']) as image:
        for entry in image:
            print(entry.path)
```

### Response
- Returns: `list[dict]` - A list of dictionaries, where each dictionary represents a found superblock and contains keys like `offset`, `compression`, `bytes_used`, and `inodes`.
```

--------------------------------

### Scan Squashfs Image for Superblocks

Source: https://github.com/matteomattei/pysquashfsimage/blob/master/README.md

Scans a squashfs image file to find and display all superblocks. This command provides detailed information about the filesystem's structure, including magic number, version, timestamps, and sizes.

```bash
$ pysquashfs scan myimage.img
```

--------------------------------

### Extract Entire Directory Tree

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Recursively extracts a directory and all its contents to the local filesystem, preserving file types, metadata, and hard links. Set `force=True` to overwrite existing files.

```python
from PySquashfsImage import SquashFsImage
from PySquashfsImage.extract import extract_dir

with SquashFsImage.from_file('image.img') as image:
    etc = image.select('/etc')
    if etc and etc.is_dir:
        extract_dir(etc, '/tmp/extracted_etc', force=True, quiet=False)
        # Output:
        # extract /etc to /tmp/extracted_etc
        # extract /etc/passwd to /tmp/extracted_etc/passwd
        # extract /etc/group to /tmp/extracted_etc/group
        # ...

    # Extract full filesystem
    root = image.root
    extract_dir(root, '/tmp/squashfs-root', force=False)
```

--------------------------------

### Recursively Iterate Over Directory Contents

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Yields a directory and all its descendants (files and subdirectories) in depth-first order. Useful for counting files, finding specific types of entries, or processing directory structures.

```python
from PySquashfsImage import SquashFsImage

with SquashFsImage.from_file('image.img') as image:
    # Count all regular files
    regular_files = [f for f in image.root.riter() if f.is_file]
    print(f"Total regular files: {len(regular_files)}")

    # Find all symlinks
    symlinks = [f for f in image if f.is_symlink]
    for lnk in symlinks:
        print(f"{lnk.path} -> {lnk.readlink()}")

    # Iterate a specific subdirectory recursively
    usr = image.select('/usr')
    if usr:
        for entry in usr.riter():
            print(entry.path, entry.filemode)
```

--------------------------------

### Scan for SquashFS Superblocks

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Scans a file path, file-like object, or bytes for squashfs 4.0 superblocks. Returns a list of dictionaries, each containing the offset and details of a found superblock. This is useful for identifying embedded squashfs filesystems within larger binary blobs like firmware.

```python
from PySquashfsImage.util import find_superblocks
from PySquashfsImage import SquashFsImage

# Scan a firmware image for embedded squashfs filesystems
superblocks = find_superblocks('firmware.bin')
for sb in superblocks:
    print(f"Superblock at offset {sb['offset']}:")
    print(f"  Compression: {sb['compression']}")
    print(f"  Size: {sb['bytes_used']} bytes")
    print(f"  Inodes: {sb['inodes']}")

# Then open each one
for sb in superblocks:
    with SquashFsImage.from_file('firmware.bin', offset=sb['offset']) as image:
        for entry in image:
            print(entry.path)
```

--------------------------------

### SquashFsImage.from_bytes(bytes_, offset=0)

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Creates a SquashFsImage object directly from a bytes object. This is useful when the image data is already in memory, such as after being downloaded or read from a network stream.

```APIDOC
## SquashFsImage.from_bytes(bytes_, offset=0)

### Description
Creates a `SquashFsImage` from a `bytes` object. Useful when the image has already been loaded into memory or received over a network.

### Method
`SquashFsImage.from_bytes`

### Parameters
#### Path Parameters
- **bytes_** (bytes) - Required - The raw bytes of the squashfs image.
- **offset** (integer) - Optional - The byte offset to the superblock. Defaults to 0.

### Request Example
```python
from PySquashfsImage import SquashFsImage

with open('/path/to/image.img', 'rb') as f:
    raw = f.read()

with SquashFsImage.from_bytes(raw) as image:
    for item in image:
        if not item.is_dir:
            print(item.path)
```

### Response
#### Success Response (SquashFsImage object)
- **image** (SquashFsImage) - An object representing the opened squashfs image, usable as a context manager.

#### Response Example
(See Request Example for usage)
```

--------------------------------

### Stream File Content Block by Block

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Streams the content of a file in blocks, matching the image's internal block size. This method is recommended for large files to avoid loading the entire content into memory.

```python
from PySquashfsImage import SquashFsImage

with SquashFsImage.from_file('image.img') as image:
    huge = image.select('/usr/share/data/large_dataset.bin')
    if huge and huge.is_file:
        total = 0
        with open('extracted_large.bin', 'wb') as out:
            for block in huge.iter_bytes():
                out.write(block)
                total += len(block)
        print(f"Wrote {total} bytes")
```

--------------------------------

### RegularFile.iter_bytes()

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Streams a file's content block by block using a generator. Ideal for handling large files efficiently.

```APIDOC
## RegularFile.iter_bytes()

### Description
Returns a generator that yields raw bytes blocks, matching the image's internal block size. Use this for large files to avoid memory exhaustion.

### Method
`iter_bytes()`

### Parameters
None

### Request Example
```python
from PySquashfsImage import SquashFsImage

with SquashFsImage.from_file('image.img') as image:
    huge = image.select('/usr/share/data/large_dataset.bin')
    if huge and huge.is_file:
        total = 0
        with open('extracted_large.bin', 'wb') as out:
            for block in huge.iter_bytes():
                out.write(block)
                total += len(block)
        print(f"Wrote {total} bytes")
```

### Response
- Returns: `generator` - Yields bytes blocks of the file content.
```

--------------------------------

### RegularFile.read_bytes()

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Reads the complete uncompressed content of a regular file as a bytes object. Prefer `iter_bytes()` for large files.

```APIDOC
## RegularFile.read_bytes()

### Description
Returns the complete uncompressed content of a regular file as a `bytes` object. For large files, prefer `iter_bytes()` to avoid loading everything into memory at once.

### Method
`read_bytes()`

### Parameters
None

### Request Example
```python
from PySquashfsImage import SquashFsImage

with SquashFsImage.from_file('image.img') as image:
    config = image.select('/etc/config.json')
    if config and config.is_file:
        content = config.read_bytes()
        print(content.decode('utf-8'))
```

### Response
- Returns: `bytes` - The uncompressed content of the file.
```

--------------------------------

### Read Full File Content as Bytes

Source: https://context7.com/matteomattei/pysquashfsimage/llms.txt

Reads the entire uncompressed content of a regular file into memory as a bytes object. For large files, consider using `iter_bytes()` to prevent memory exhaustion.

```python
from PySquashfsImage import SquashFsImage

with SquashFsImage.from_file('image.img') as image:
    config = image.select('/etc/config.json')
    if config and config.is_file:
        content = config.read_bytes()
        print(content.decode('utf-8'))

    # For text files, use read_text() directly
    readme = image.find('README')
    if readme:
        text = readme.read_text(encoding='utf-8', errors='replace')
        print(text[:200])
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.