Pkg.CPIO — API for parsing CPIO archives

Overview

The Pkg.CPIO module contains the API for parsing CPIO archives.

CPIO is a stream-based Unix archive format that concatenates per-file headers followed by file data. The module supports all common header variants: old binary (little- and big-endian, magic 0o070707), POSIX old ASCII / odc (magic "070707"), SVR4 ASCII / newc (magic "070701"), and SVR4 ASCII with CRC (magic "070702"). Every variant terminates the archive with an entry whose name is "TRAILER!!!". CPIO is commonly produced by find | cpio -o and is the on-disk format used by Linux initramfs images.

Enumerating CPIO Entries

The following code example demonstrates how to enumerate entries in a CPIO archive:

from Pro.Core import *
from Pkg.CPIO import *

def enumerateEntries(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    obj = CPIOObject()
    if not obj.Load(c) or not obj.Initialize():
        return
    print("Variant:", obj.GetVariant())
    offs = None
    while True:
        e, offs = obj.NextEntry(offs)
        if e is None:
            break
        print(e.name, e.data_size, oct(e.mode))

Module API

Pkg.CPIO module API.

Classes:

CPIOEntry()	This class represents a single entry in a CPIO archive.
CPIOObject()	This class represents a CPIO archive.

class CPIOEntry

This class represents a single entry in a CPIO archive.

Instances are produced by CPIOObject.NextEntry() and CPIOObject.GetEntry(). Fields reflect the values stored in the on-disk header after decoding; binary, octal, and hexadecimal field encodings are all normalised to plain Python integers.

Attributes:

check	The header checksum (only set for the "crc" variant; always zero otherwise).
data_offset	The byte offset of the file data in the archive stream.
data_size	The size of the file data in bytes.
dev_major	The major number of the device containing the file.
dev_minor	The minor number of the device containing the file.
gid	The group id.
header_offset	The byte offset of the header in the archive stream.
header_size	The size of the header in bytes.
ino	The inode number.
mode	The file mode, including the file-type bits in the upper bits.
mtime	The modification time, as a Unix epoch timestamp.
name	The file name, decoded as UTF-8 with replacement.
name_offset	The byte offset of the file name in the archive stream.
namesize	The size of the file name in bytes, including the trailing NUL.
next_offset	The byte offset of the next header in the archive stream.
nlink	The number of hard links.
rdev_major	The major number of the device the file refers to (for device nodes).
rdev_minor	The minor number of the device the file refers to (for device nodes).
uid	The user id.
variant	The header variant: "bin", "bin_be", "odc", "newc", or "crc".

check: int

The header checksum (only set for the "crc" variant; always zero otherwise).

data_offset: int

The byte offset of the file data in the archive stream.

data_size: int

The size of the file data in bytes.

dev_major: int

The major number of the device containing the file.

dev_minor: int

The minor number of the device containing the file.

gid: int

The group id.

header_offset: int

The byte offset of the header in the archive stream.

header_size: int

The size of the header in bytes.

ino: int

The inode number.

mode: int

The file mode, including the file-type bits in the upper bits.

mtime: int

The modification time, as a Unix epoch timestamp.

name: str

The file name, decoded as UTF-8 with replacement.

name_offset: int

The byte offset of the file name in the archive stream.

namesize: int

The size of the file name in bytes, including the trailing NUL.

next_offset: int

The byte offset of the next header in the archive stream.

nlink: int

The number of hard links.

rdev_major: int

The major number of the device the file refers to (for device nodes).

rdev_minor: int

The minor number of the device the file refers to (for device nodes).

uid: int

The user id.

variant: str

The header variant: "bin", "bin_be", "odc", "newc", or "crc".

class CPIOObject

Bases: Pro.Core.CFFObject

This class represents a CPIO archive.

The CPIO archive format is a stream-based Unix archive that concatenates per-file headers followed by file data. CPIO comes in several header variants: old binary (magic 0o070707 stored as 2 bytes), old POSIX ASCII / odc (magic "070707", 76-byte header), SVR4 ASCII / newc (magic "070701", 110-byte header), and SVR4 ASCII with CRC (magic "070702"). Every variant terminates the archive with an entry whose name is "TRAILER!!!". CPIO is commonly produced by find | cpio -o and used as the on-disk format for Linux initramfs images.

Methods:

DumpDefects(out)	Dumps a human-readable description of the recorded defects to a text stream.
DumpEntry(entry, out)	Dumps information about an entry to a text stream.
GetEndOffset()	Returns the offset of the byte after the trailer entry (including any trailing zero padding to the next 512-byte block).
GetEntry(offset)	Retrieves an entry by its offset.
GetEntryData(entry)	Retrieves the data of an entry.
GetVariant()	Returns the header variant detected in the archive.
HasDefects()	Returns whether any defects were recorded while parsing the archive.
IsDirectory(entry)	Checks whether an entry is a directory.
NextEntry([curoffs])	Iterates over the entries.
ParseArchive()	Parses the archive.

DumpDefects(out: Pro.Core.NTTextStream) → None

Dumps a human-readable description of the recorded defects to a text stream.

Parameters

out (NTTextStream) – The output text stream.

See also HasDefects().

DumpEntry(entry: Any, out: Pro.Core.NTTextStream) → None

Dumps information about an entry to a text stream.

Parameters

• entry (Any) – The entry.

• out (NTTextStream) – The output text stream.

GetEndOffset() → int

Returns the offset of the byte after the trailer entry (including any trailing zero padding to the next 512-byte block).

Returns

Returns the offset of the byte just past the end of the archive.

Return type

int

GetEntry(offset: int) → Any

Retrieves an entry by its offset.

Parameters

offset (int) – The entry offset.

Returns

Returns the entry if successful; otherwise returns None.

See also NextEntry().

GetEntryData(entry: Any) → Pro.Core.NTContainer

Retrieves the data of an entry.

Parameters

entry (Any) – The entry.

Returns

Returns the data if successful; otherwise returns an invalid container.

Return type

NTContainer

See also NextEntry() and GetEntry().

GetVariant() → str

Returns the header variant detected in the archive.

Returns

One of "bin" (old binary, little-endian), "bin_be" (old binary, big-endian), "odc" (POSIX old ASCII), "newc" (SVR4 ASCII, no CRC), or "crc" (SVR4 ASCII with CRC).

Return type

str

HasDefects() → bool

Returns whether any defects were recorded while parsing the archive.

A defect is recorded when the archive is malformed in some way that did not prevent the parser from extracting at least the minimum amount of structural evidence required to recognise it as CPIO: most commonly a missing "TRAILER!!!" entry (the archive is truncated), a header whose magic does not match any known variant in the middle of the stream, or size fields that fail to advance the stream cursor.

Returns

Returns True if at least one defect was recorded; otherwise returns False.

Return type

bool

See also DumpDefects().

IsDirectory(entry: Any) → bool

Checks whether an entry is a directory.

Parameters

entry (Any) – The entry.

Returns

Returns True if the entry is a directory; otherwise returns False.

Return type

bool

See also NextEntry() and GetEntry().

NextEntry(curoffs: Optional[int] = None) → Tuple[Any, int]

Iterates over the entries.

Parameters

curoffs (Optional[int]) – The current offset.

Returns

Returns a tuple containing the next entry and its offset if successful; otherwise returns a tuple containing two None values.

Return type

Tuple[Any, int]

See also GetEntry().

ParseArchive() → bool

Parses the archive.

Returns

Returns True if successful; otherwise returns False.

Return type

bool