pub struct ContainerCaps {Show 17 fields
pub read: bool,
pub write: bool,
pub forward_parse: bool,
pub degraded_parse: bool,
pub trailing_index: bool,
pub solid: bool,
pub per_entry_codec: bool,
pub needs_seek: bool,
pub stores_dirs: bool,
pub stores_symlinks: bool,
pub detects_corruption: CorruptionDetection,
pub salvage: bool,
pub unique_names: bool,
pub nul_in_names: bool,
pub nul_in_link_targets: bool,
pub stores_ownership: bool,
pub stores_hardlinks: bool,
}Expand description
What a container can do, and what it needs from its input.
Fields§
§read: bool§write: bool§forward_parse: boolEntries can be enumerated from a forward-only source at full data fidelity (metadata may be approximate). True for zip, tar, cpio.
degraded_parse: boolOnly a best-effort salvage scan is possible forward-only. Distinct from
forward_parse: this rung yields partial results by construction.
trailing_index: boolThe authoritative index lives at the end of the stream (zip, 7z, rar).
solid: boolEntries share codec state, so reaching entry N decodes 1..N (7z, rar).
per_entry_codec: boolEach entry carries its own codec (zip, 7z).
needs_seek: boolRandom access is required even to enumerate (squashfs, iso).
stores_dirs: boolA directory can be recorded AS a directory, rather than as an empty regular file that happens to share its name.
ar is the counter-example and the reason this field exists: its
format has no directory concept at all, so writing one produces a
zero-byte file named proj/sub — after which an entry named
proj/sub/a.txt cannot be extracted, because its parent is a file.
A writer that cannot store the kind is expected to be told so by its
caller and warn, rather than emit the lie.
stores_symlinks: boolA symlink can be recorded as a link, target and all, rather than as a regular file carrying the target text as its contents.
detects_corruption: CorruptionDetectionWhether reading an archive of this format will NOTICE a corrupted
byte rather than silently returning wrong data — and, where it does,
what kind of guarantee that is. The container-side twin of
CodecCaps::detects_corruption, reusing the same enum and the same
three meanings.
Read by the read-only conformance harness’s corruption property, and
it is the reason that property is honest rather than merely strict:
the harness flips the fixture’s middle byte and demands the read-back
differ from the expectation, which a container with no integrity
check at all cannot promise. A fixture whose midpoint lands in a
reserved, comment or padding field no reader consults would fail a
CORRECT container, and the module’s own rule is that properties skip
on evidence, never on trust — ContainerCaps being one of the two
admissible kinds of evidence.
Defaults to CorruptionDetection::Never via Self::read_only,
Self::read_write and Default, so a container claims this the
same way it claims every other capability here: explicitly. lha
(CRC-16 per entry) and arj (CRC-32 per entry) are the first two to
declare it.
salvage: boolstuffr salvage has a scanner for this container: it can scan a
damaged archive for entries, report what it proved about each, and
write what it recovered.
The one answer to “is salvage supported”, read by stuffr formats’
SALVAGE column and by stuffr::entries::salvage, which refuses a
container saying false at exit 3 before scanning a byte. It is NOT
the dispatch: the facade still maps a format to its scanner by name,
and a test there pins the two to each other for every container a
build registers, in both directions.
It says nothing about how much a recovered entry can be trusted —
that is a per-format class of evidence
(crate::salvage::Attestation), owned beside the scanner dispatch.
Defaults to false via Self::read_only, Self::read_write and
Default, like every other capability here: a container claims it
explicitly, in the same commit that wires its scanner.
unique_names: boolThe writer refuses a second entry under a name it has already written, so an archive of this format holds one entry per name.
zip is the case: zip 8.6.0’s ZipWriter answers Duplicate filename, while tar, cpio and ar append a repeat like any other
entry. Read by stuffr convert, whose source can legitimately repeat
a name (pack’s walk never does), to keep the first entry of each
name and warn about the rest rather than fail on the writer’s refusal.
false via Self::read_only, Self::read_write and Default;
every registered container states it explicitly.
nul_in_names: boolAn entry name containing a NUL byte is stored whole by the writer.
false for a format whose name field is NUL-terminated or
NUL-padded — tar’s ustar field and GNU L payload, cpio newc’s
c_namesize name, ar’s BSD #1/N name (its trailing NULs are
stripped on read), ARJ’s header string, ARC’s and ZOO’s fixed fields
— where the name would otherwise come back shorter than it went in.
Every such writer refuses the name itself (a backstop); stuffr convert, whose source can legitimately carry one (an ar or zip
member name), reads this to skip the entry with a warning instead
(plan_entry_write). pack never meets one: an OS path cannot hold
a NUL. true for zip and LHA, whose names are length-prefixed, so
the writer stores a NUL exactly as given. zip reads it back whole;
stuffr’s LHA reader renders it %00, as it does every byte outside
printable ASCII (lha_name_from_parts): the byte is in the archive,
and only stuffr’s rendering of it differs.
false via Self::read_only, Self::read_write and Default,
the safe answer for a container that has not been audited; every
registered container states it explicitly.
nul_in_link_targets: boolA symlink TARGET containing a NUL byte is stored, and read back,
whole. The sibling of Self::nul_in_names, and deliberately a
separate flag: tar and cpio differ on exactly this.
false for tar, whose link target lives in the NUL-terminated
linkname field (or a GNU K payload, also NUL-terminated) — its
writer refuses one as a backstop, and stuffr convert skips such a
symlink with a warning instead (plan_entry_write). true for cpio
newc and zip, which store the target as the entry’s BODY, by length
(measured round trip). A container with no symlink entries
(!stores_symlinks) states what its format would imply: false for
ar, arj, arc and zoo, which have no link representation at all;
true for LHA, whose name|target convention lives in its
length-prefixed name field.
false via Self::read_only, Self::read_write and Default;
every registered container states it explicitly.
stores_ownership: boolThe writer records an entry’s owner — its uid and gid — so a missing
one is a real loss: tar, cpio and ar write meta.uid.unwrap_or(0),
so an entry with no ids would assert root:root.
false for a format with no owner field the writer fills: zip (the
Info-ZIP ux extra field is not written), LHA (no UNIX extension
header is written), ARJ, ARC and ZOO. Read by plan_entry_write, the
one owner of the ownership warning: an entry with no ids costs nothing
in a target that would not have stored them anyway, so stuffr convert
from lha to zip reports no uid_gid loss.
false via Self::read_only, Self::read_write and Default;
every registered container states it explicitly.
stores_hardlinks: boolThe container’s WRITER can store an crate::EntryKind::Hardlink as
a link, rather than only as a second copy of the bytes.
true for tar alone (typeflag 1). false for cpio, whose writer
writes ino=0, nlink=1 for every entry, so a real cpio link would
first need a unique inode per file; and for zip, ar, LHA, ARJ, ARC and
ZOO, which have no link concept at all. Read by plan_entry_write,
the one owner of what a target cannot hold.
false via Self::read_only, Self::read_write and Default;
every registered container states it explicitly.
Implementations§
Source§impl ContainerCaps
impl ContainerCaps
Sourcepub const fn read_only() -> Self
pub const fn read_only() -> Self
A container that can be read but not written — RAR, whose compressor is proprietary.
Sourcepub const fn read_write() -> Self
pub const fn read_write() -> Self
A container supporting both directions. Every other capability stays false — a constructor must not claim what a format has not.