use std::io::{Read, Seek, SeekFrom, Write};
use std::ops::ControlFlow;
use crate::bytes::{get_u16, get_u32};
use crate::fidelity::Synthesis;
use crate::finding::{Family, Finding, Findings, Severity};
use crate::io::{offset_of, read_exact_at};
use crate::path::is_hostile_component;
use crate::policy::{Limits, MAX_PATH, OpenOptions, ReadPolicy};
use crate::time::Timestamp;
use crate::tree::{Attributes, FsTree, NodeKind, TreeEntry, TreeError};
use super::geometry::{ExfatLayout, FIRST_CLUSTER, layout_from_boot};
use super::model::MAX_DIRECTORY_BYTES;
use super::ondisk::{
AllocationBitmapEntry, BAD_CLUSTER, BOOT_REGION_SECTORS, CHECKSUM_SECTOR, DIR_ENTRY_SIZE,
EXTENDED_BOOT_FIRST_SECTOR, EXTENDED_BOOT_SECTORS, EXTENDED_BOOT_SIGNATURE, EntryType,
FAT_ENTRY_MEDIA, FAT_ENTRY_RESERVED, FILE_SYSTEM_MINOR_REVISION, FileAttributes, FileEntry,
FileNameEntry, MAIN_BOOT_REGION_SECTOR, MAX_LABEL_UNITS, MainBootSector, NAME_UNITS_PER_ENTRY,
PERCENT_IN_USE_MAX, PERCENT_IN_USE_UNKNOWN, ParseError, SECONDARY_ALLOCATION_POSSIBLE,
StreamExtensionEntry, UpcaseTable, UpcaseTableEntry, VOLUME_FLAG_MEDIA_FAILURE,
VOLUME_FLAG_VOLUME_DIRTY, VolumeLabelEntry, boot_checksum, checksum_sector_value,
entry_set_checksum, extended_boot_signature, name_hash, percent_in_use, unpack_timestamp,
upcase_checksum, utc_offset_minutes,
};
const MAX_UPCASE_BYTES: u64 = 2 * 0x1_0000;
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub enum Category {
BootRegion,
AllocationTable,
AllocationBitmap,
UpcaseTable,
Directory,
}
impl Category {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Category::BootRegion => "boot region",
Category::AllocationTable => "allocation table",
Category::AllocationBitmap => "allocation bitmap",
Category::UpcaseTable => "up-case table",
Category::Directory => "directory",
}
}
}
crate::naming::serialize_as_name!(Category);
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct Location {
pub sector: Option<u64>,
pub cluster: Option<u32>,
pub entry: Option<u32>,
}
impl Location {
fn or(self, other: Self) -> Self {
Self {
sector: self.sector.or(other.sector),
cluster: self.cluster.or(other.cluster),
entry: self.entry.or(other.entry),
}
}
const fn at_entry(index: u32) -> Self {
Self {
sector: None,
cluster: None,
entry: Some(index),
}
}
const fn at_cluster(cluster: u32) -> Self {
Self {
sector: None,
cluster: Some(cluster),
entry: None,
}
}
const fn at_sector(sector: u64) -> Self {
Self {
sector: Some(sector),
cluster: None,
entry: None,
}
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct Anomaly {
pub severity: Severity,
pub category: Category,
pub location: Location,
pub detail: String,
}
impl crate::Deviation for Anomaly {
fn severity(&self) -> Severity {
self.severity
}
fn to_finding(&self, unit: u32) -> Finding {
Anomaly::to_finding(self, unit)
}
}
impl Anomaly {
#[must_use]
pub fn to_finding(&self, bytes_per_sector: u32) -> Finding {
let Self {
severity,
category,
location,
detail,
} = self;
let Location {
sector,
cluster,
entry,
} = *location;
crate::finding::project(
*severity,
Family::ExFat,
category.as_str(),
&[
("cluster", cluster.map(u64::from)),
("sector", sector),
("entry", entry.map(u64::from)),
],
sector,
bytes_per_sector,
detail,
)
}
}
#[derive(Clone, PartialEq, Eq, Debug, thiserror::Error)]
#[non_exhaustive]
pub enum ReadError {
#[error("i/o error: {message}")]
#[non_exhaustive]
Io {
kind: std::io::ErrorKind,
message: String,
},
#[error(transparent)]
Parse(#[from] ParseError),
#[error("the boot sector does not describe an exFAT volume: {detail}")]
#[non_exhaustive]
BadBootSector {
detail: String,
},
#[error("this volume records two allocation tables, which is the transaction-safe variant")]
TexFat,
#[error("a volume with {count} allocation tables is not one the format defines")]
#[non_exhaustive]
FatCount {
count: u8,
},
#[error(
"the boot region at sector {sector} checksums to {computed:#010x} and records \
{stored:#010x}"
)]
#[non_exhaustive]
BootChecksumMismatch {
sector: u64,
computed: u32,
stored: u32,
},
#[error("the checksum sector of the boot region at sector {sector} does not repeat one value")]
#[non_exhaustive]
BootChecksumSectorSplit {
sector: u64,
},
#[error(
"the backup boot region at sector {sector} does not describe the same volume: {detail}"
)]
#[non_exhaustive]
BackupBootRegionDiffers {
sector: u64,
detail: String,
},
#[error(
"this volume records minor revision {minor} of the format, which this reader does not know"
)]
#[non_exhaustive]
UnknownMinorRevision {
minor: u8,
},
#[error(
"the extended boot sector at sector {sector} ends with {found:#010x} and the format \
requires {expected:#010x}"
)]
#[non_exhaustive]
BadExtendedBootSignature {
sector: u64,
found: u32,
expected: u32,
},
#[error("cluster {cluster} is not a cluster this volume has")]
#[non_exhaustive]
ClusterOutOfRange {
cluster: u32,
},
#[error("the chain reaches cluster {cluster}, which the allocation table marks bad")]
#[non_exhaustive]
BadClusterInChain {
cluster: u32,
},
#[error("the table entry for cluster {cluster} is {entry:#010x}, which no chain may contain")]
#[non_exhaustive]
BadChainEntry {
cluster: u32,
entry: u32,
},
#[error("the chain from cluster {start} does not end within the volume's {clusters} clusters")]
#[non_exhaustive]
ChainTooLong {
start: u32,
clusters: u32,
},
#[error("a stream from cluster {start} holds {held} bytes and its entry records {declared}")]
#[non_exhaustive]
StreamTooShort {
start: u32,
declared: u64,
held: u64,
},
#[error("table entry {index} is {found:#010x} where the format defines {expected:#010x}")]
#[non_exhaustive]
BadReservedEntry {
index: u32,
found: u32,
expected: u32,
},
#[error("the root directory describes no {resident}, which every volume carries")]
#[non_exhaustive]
MissingResident {
resident: &'static str,
},
#[error("the up-case table checksums to {computed:#010x} and its entry records {stored:#010x}")]
#[non_exhaustive]
UpcaseChecksumMismatch {
computed: u32,
stored: u32,
},
#[error("an up-case table of {bytes} bytes is longer than the {limit} a mapping can need")]
#[non_exhaustive]
UpcaseTooLong {
bytes: u64,
limit: u64,
},
#[error(
"an allocation bitmap of {bytes} bytes does not hold one bit for each of {clusters} clusters"
)]
#[non_exhaustive]
BitmapWrongSize {
bytes: u64,
clusters: u32,
},
#[error(
"the entry set at entry {index} checksums to {computed:#06x} and records {stored:#06x}"
)]
#[non_exhaustive]
SetChecksumMismatch {
index: u32,
computed: u16,
stored: u16,
},
#[error("the entry set at entry {index} is not complete: {detail}")]
#[non_exhaustive]
IncompleteEntrySet {
index: u32,
detail: String,
},
#[error("entry {index} continues a set that no entry opened")]
#[non_exhaustive]
StraySecondaryEntry {
index: u32,
},
#[error("entry {index} is of critical type {entry_type:#04x}, which this reader does not know")]
#[non_exhaustive]
UnknownCriticalEntry {
index: u32,
entry_type: u8,
},
#[error("the name at entry {index} is not well-formed UTF-16")]
#[non_exhaustive]
IllFormedName {
index: u32,
},
#[error(
"the name at entry {index} hashes to {computed:#06x} and its entry records {stored:#06x}"
)]
#[non_exhaustive]
NameHashMismatch {
index: u32,
computed: u16,
stored: u16,
},
#[error("the name at entry {index} is one no directory can hold")]
#[non_exhaustive]
HostileName {
index: u32,
},
#[error("the entry set at entry {index} carries {have} name entries and its name needs {want}")]
#[non_exhaustive]
ExcessNameEntries {
want: usize,
have: usize,
index: u32,
},
#[error("a {entry_type} entry sits at entry {index} of a directory that is not the root")]
#[non_exhaustive]
MisplacedRootEntry {
index: u32,
entry_type: &'static str,
},
#[error("a second {entry_type} entry sits at entry {index} of the root directory")]
#[non_exhaustive]
DuplicateRootEntry {
index: u32,
entry_type: &'static str,
},
#[error("a volume label of {count} characters is longer than the {limit} the field holds")]
#[non_exhaustive]
LabelTooLong {
count: u8,
limit: usize,
},
#[error("the volume label carries a NUL, which is what the field's padding is")]
LabelNulUnit,
#[error("directory entry {index} follows the end marker and no reader reaches it")]
#[non_exhaustive]
EntriesAfterEnd {
index: u32,
},
#[error("the directory at entry {index} records no clusters, so it holds no entries at all")]
#[non_exhaustive]
DirectoryWithoutAllocation {
index: u32,
},
#[error("the stream at entry {index} records {declared} bytes and no first cluster")]
#[non_exhaustive]
StreamWithoutAllocation {
index: u32,
declared: u64,
},
#[error("the stream at entry {index} records no bytes and a first cluster of {first_cluster}")]
#[non_exhaustive]
AllocationWithoutLength {
index: u32,
first_cluster: u32,
},
#[error("a stream of {declared} bytes is longer than the {limit} bytes the cluster heap holds")]
#[non_exhaustive]
StreamPastHeap {
declared: u64,
limit: u64,
},
#[error(
"the directory at entry {index} records {declared} bytes, more than the {limit} the \
format allows one"
)]
#[non_exhaustive]
DirectoryTooLong {
index: u32,
declared: u64,
limit: u64,
},
#[error(
"the directory at entry {index} records {declared} bytes, which is not whole clusters \
of {bytes_per_cluster}"
)]
#[non_exhaustive]
DirectoryLengthNotClusters {
index: u32,
declared: u64,
bytes_per_cluster: u32,
},
#[error(
"the entry at entry {index} sets attribute bits {bits:#06x}, which the format reserves"
)]
#[non_exhaustive]
ReservedAttributes {
index: u32,
bits: u16,
},
#[error("the stream at entry {index} records an allocation and does not declare one possible")]
#[non_exhaustive]
AllocationNotPossible {
index: u32,
},
#[error("the {field} at entry {index} holds a value the encoding does not define")]
#[non_exhaustive]
MalformedTimestamp {
index: u32,
field: &'static str,
},
#[error("a stream records {valid} bytes written of a length of {declared}")]
#[non_exhaustive]
ValidLengthPastEnd {
valid: u64,
declared: u64,
},
#[error("a stream of {declared} bytes has {valid} of them written; the rest reads as zeros")]
#[non_exhaustive]
ValidLengthTrails {
valid: u64,
declared: u64,
},
#[error("cluster {cluster} is occupied and the allocation bitmap says it is free")]
#[non_exhaustive]
ClusterNotAllocated {
cluster: u32,
},
#[error("{count} clusters are marked in use and reached by nothing, the first at {first}")]
#[non_exhaustive]
LostClusters {
count: u64,
first: u32,
},
#[error("cluster {cluster} is occupied by more than one stream")]
#[non_exhaustive]
CrossLinkedCluster {
cluster: u32,
},
#[error(
"the volume records a PercentInUse of {stated}, and the field holds 0 to 100 or 255 \
for not known"
)]
#[non_exhaustive]
PercentInUseOutOfRange {
stated: u8,
},
#[error(
"the volume records that it is {stated}% in use and {in_use} of its {clusters} \
clusters are, which is {actual}%"
)]
#[non_exhaustive]
PercentInUseStale {
stated: u8,
in_use: u64,
clusters: u32,
actual: u8,
},
#[error("this volume was not cleanly unmounted, so its metadata may not describe its contents")]
VolumeDirty,
#[error("a driver recorded a failure of the medium this volume is on")]
MediaFailure,
#[error("no such path: {}", crate::escape::printable(.path))]
#[non_exhaustive]
NotFound {
path: Vec<u8>,
},
#[error("not a directory: {}", crate::escape::printable(.path))]
#[non_exhaustive]
NotADirectory {
path: Vec<u8>,
},
#[error("a file of {size} bytes exceeds the {limit}-byte read limit")]
#[non_exhaustive]
FileTooLarge {
size: u64,
limit: u64,
},
#[error("a walked path is longer than the {limit} bytes a path may be")]
#[non_exhaustive]
PathTooLong {
limit: usize,
},
#[error("the tree holds more than {limit} names")]
#[non_exhaustive]
WalkTooLarge {
limit: usize,
},
}
crate::io::io_error!(ReadError);
impl ReadError {
#[must_use]
pub fn anomaly(&self) -> Anomaly {
let (severity, category, location) = match self {
ReadError::Io { .. } => (
Severity::Structural,
Category::BootRegion,
Location::default(),
),
ReadError::Parse(_) | ReadError::BadBootSector { .. } => (
Severity::Structural,
Category::BootRegion,
Location::at_sector(MAIN_BOOT_REGION_SECTOR),
),
ReadError::TexFat | ReadError::FatCount { .. } => (
Severity::Structural,
Category::BootRegion,
Location::at_sector(MAIN_BOOT_REGION_SECTOR),
),
ReadError::BootChecksumMismatch { sector, .. }
| ReadError::BootChecksumSectorSplit { sector } => (
Severity::Integrity,
Category::BootRegion,
Location::at_sector(*sector),
),
ReadError::BackupBootRegionDiffers { sector, .. }
| ReadError::BadExtendedBootSignature { sector, .. } => (
Severity::Conformance,
Category::BootRegion,
Location::at_sector(*sector),
),
ReadError::UnknownMinorRevision { .. } => (
Severity::Conformance,
Category::BootRegion,
Location::at_sector(MAIN_BOOT_REGION_SECTOR),
),
ReadError::ClusterOutOfRange { cluster }
| ReadError::BadChainEntry { cluster, .. }
| ReadError::BadClusterInChain { cluster }
| ReadError::ChainTooLong { start: cluster, .. }
| ReadError::StreamTooShort { start: cluster, .. } => (
Severity::Structural,
Category::AllocationTable,
Location::at_cluster(*cluster),
),
ReadError::BadReservedEntry { .. } => (
Severity::Conformance,
Category::AllocationTable,
Location::default(),
),
ReadError::MissingResident { .. } => (
Severity::Structural,
Category::Directory,
Location::default(),
),
ReadError::UpcaseChecksumMismatch { .. } => (
Severity::Integrity,
Category::UpcaseTable,
Location::default(),
),
ReadError::UpcaseTooLong { .. } => (
Severity::Structural,
Category::UpcaseTable,
Location::default(),
),
ReadError::BitmapWrongSize { .. } => (
Severity::Structural,
Category::AllocationBitmap,
Location::default(),
),
ReadError::SetChecksumMismatch { index, .. }
| ReadError::NameHashMismatch { index, .. } => (
Severity::Integrity,
Category::Directory,
Location::at_entry(*index),
),
ReadError::HostileName { index }
| ReadError::IncompleteEntrySet { index, .. }
| ReadError::StraySecondaryEntry { index }
| ReadError::DirectoryWithoutAllocation { index }
| ReadError::StreamWithoutAllocation { index, .. }
| ReadError::DirectoryTooLong { index, .. } => (
Severity::Structural,
Category::Directory,
Location::at_entry(*index),
),
ReadError::UnknownCriticalEntry { index, .. }
| ReadError::IllFormedName { index }
| ReadError::MisplacedRootEntry { index, .. }
| ReadError::DuplicateRootEntry { index, .. }
| ReadError::ExcessNameEntries { index, .. }
| ReadError::EntriesAfterEnd { index }
| ReadError::DirectoryLengthNotClusters { index, .. }
| ReadError::ReservedAttributes { index, .. }
| ReadError::AllocationNotPossible { index }
| ReadError::AllocationWithoutLength { index, .. }
| ReadError::MalformedTimestamp { index, .. } => (
Severity::Conformance,
Category::Directory,
Location::at_entry(*index),
),
ReadError::ValidLengthPastEnd { .. } | ReadError::StreamPastHeap { .. } => (
Severity::Structural,
Category::Directory,
Location::default(),
),
ReadError::LabelTooLong { .. } | ReadError::LabelNulUnit => (
Severity::Conformance,
Category::Directory,
Location::default(),
),
ReadError::ValidLengthTrails { .. } => {
(Severity::Cosmetic, Category::Directory, Location::default())
}
ReadError::ClusterNotAllocated { cluster }
| ReadError::CrossLinkedCluster { cluster } => (
Severity::Integrity,
Category::AllocationBitmap,
Location::at_cluster(*cluster),
),
ReadError::LostClusters { first, .. } => (
Severity::Conformance,
Category::AllocationBitmap,
Location::at_cluster(*first),
),
ReadError::VolumeDirty
| ReadError::MediaFailure
| ReadError::PercentInUseStale { .. } => (
Severity::Cosmetic,
Category::BootRegion,
Location::at_sector(MAIN_BOOT_REGION_SECTOR),
),
ReadError::PercentInUseOutOfRange { .. } => (
Severity::Conformance,
Category::BootRegion,
Location::at_sector(MAIN_BOOT_REGION_SECTOR),
),
ReadError::NotFound { .. }
| ReadError::NotADirectory { .. }
| ReadError::FileTooLarge { .. }
| ReadError::PathTooLong { .. }
| ReadError::WalkTooLarge { .. } => (
Severity::Structural,
Category::Directory,
Location::default(),
),
};
Anomaly {
severity,
category,
location,
detail: self.to_string(),
}
}
}
impl From<ReadError> for TreeError {
fn from(err: ReadError) -> Self {
match err {
ReadError::Io { kind, message } => TreeError::Io { kind, message },
ReadError::FileTooLarge { .. }
| ReadError::PathTooLong { .. }
| ReadError::WalkTooLarge { .. } => TreeError::LimitExceeded {
family: Family::ExFat,
detail: err.to_string(),
},
ReadError::TexFat | ReadError::FatCount { .. } => TreeError::Unsupported {
family: Family::ExFat,
detail: err.to_string(),
},
other => TreeError::Malformed {
family: Family::ExFat,
detail: other.to_string(),
},
}
}
}
pub type ScanReport = crate::ScanReport<Anomaly>;
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Storage {
None,
Contiguous(u32),
Chain(u32),
}
impl Storage {
#[must_use]
pub const fn first_cluster(self) -> Option<u32> {
match self {
Storage::None => None,
Storage::Contiguous(first) | Storage::Chain(first) => Some(first),
}
}
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct Times {
pub create: Timestamp,
pub access: Timestamp,
pub modify: Timestamp,
pub create_offset: Option<i32>,
pub access_offset: Option<i32>,
pub modify_offset: Option<i32>,
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct Node {
pub storage: Storage,
pub attributes: FileAttributes,
pub data_length: u64,
pub valid_data_length: u64,
pub times: Option<Times>,
}
impl Node {
#[must_use]
pub const fn is_dir(&self) -> bool {
self.attributes.contains(FileAttributes::DIRECTORY)
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct Entry {
pub name: Vec<u8>,
pub node: Node,
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct WalkEntry {
pub path: Vec<u8>,
pub node: Node,
}
pub struct Reader<R> {
src: R,
base: u64,
boot: Box<MainBootSector>,
layout: ExfatLayout,
policy: ReadPolicy,
limits: Limits,
upcase: UpcaseTable,
bitmap: Resident,
label: Option<Vec<u8>>,
root_bytes: u64,
open_anomalies: Vec<Anomaly>,
fat_window: Option<(u64, Vec<u8>)>,
bitmap_window: Option<(u64, Vec<u8>)>,
bitmap_at: Option<(u64, u32)>,
chain_cursor: Option<(u32, u64, u32)>,
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
struct Resident {
first_cluster: u32,
bytes: u64,
}
enum OnDeviation<'a> {
Policy(ReadPolicy),
Collect(&'a mut Findings<Anomaly>),
}
impl OnDeviation<'_> {
fn record(&mut self, at: Location, err: ReadError) -> Result<(), ReadError> {
match self {
OnDeviation::Policy(policy) => {
if policy.is_fatal(err.anomaly().severity) {
Err(err)
} else {
Ok(())
}
}
OnDeviation::Collect(findings) => {
let mut anomaly = err.anomaly();
anomaly.location = anomaly.location.or(at);
findings.push(anomaly);
Ok(())
}
}
}
}
struct Slot {
bytes: [u8; DIR_ENTRY_SIZE],
index: u32,
cluster: u32,
sector: u64,
}
impl Slot {
const fn entry_type(&self) -> EntryType {
EntryType(self.bytes[0])
}
const fn location(&self) -> Location {
Location {
sector: Some(self.sector),
cluster: Some(self.cluster),
entry: Some(self.index),
}
}
}
impl<R: Read + Seek> Reader<R> {
pub fn open(src: R) -> Result<Self, ReadError> {
Self::open_with(src, &OpenOptions::new())
}
pub fn open_with(mut src: R, options: &OpenOptions) -> Result<Self, ReadError> {
let end = src.seek(SeekFrom::End(0))?;
let available = end.saturating_sub(options.base);
let sector = read_exact_at(&mut src, options.base, MainBootSector::SIZE)?;
let boot = MainBootSector::read_from(§or)?;
let layout = layout_from_boot(&boot, available).map_err(|d| ReadError::BadBootSector {
detail: d.to_string(),
})?;
match boot.number_of_fats {
1 => {}
2 => return Err(ReadError::TexFat),
count => return Err(ReadError::FatCount { count }),
}
let mut reader = Self {
src,
base: options.base,
boot: Box::new(boot),
layout,
policy: options.policy,
limits: options.limits,
upcase: UpcaseTable::new(&[]),
bitmap: Resident {
first_cluster: FIRST_CLUSTER,
bytes: 0,
},
label: None,
root_bytes: 0,
open_anomalies: Vec::new(),
fat_window: None,
bitmap_window: None,
bitmap_at: None,
chain_cursor: None,
};
let mut deviations = Vec::new();
reader.check_boot_regions(&mut deviations)?;
reader.check_revision(&mut deviations);
reader.check_volume_state(&mut deviations);
reader.root_bytes = reader.measure_root()?;
reader.load_residents(&mut deviations)?;
for err in deviations {
let anomaly = err.anomaly();
if options.policy.is_fatal(anomaly.severity) {
return Err(err);
}
reader.open_anomalies.push(anomaly);
}
Ok(reader)
}
#[must_use]
pub const fn layout(&self) -> &ExfatLayout {
&self.layout
}
#[must_use]
pub fn boot_sector(&self) -> &MainBootSector {
&self.boot
}
#[must_use]
pub const fn policy(&self) -> ReadPolicy {
self.policy
}
#[must_use]
pub const fn upcase(&self) -> &UpcaseTable {
&self.upcase
}
#[must_use]
pub fn volume_label(&self) -> Option<&[u8]> {
self.label.as_deref()
}
#[must_use]
pub const fn volume_dirty(&self) -> bool {
self.boot.volume_flags & VOLUME_FLAG_VOLUME_DIRTY != 0
}
#[must_use]
pub const fn media_failure(&self) -> bool {
self.boot.volume_flags & VOLUME_FLAG_MEDIA_FAILURE != 0
}
#[must_use]
pub const fn root(&self) -> Node {
Node {
storage: Storage::Chain(self.layout.first_cluster_of_root),
attributes: FileAttributes::DIRECTORY,
data_length: self.root_bytes,
valid_data_length: self.root_bytes,
times: None,
}
}
fn check_boot_regions(&mut self, out: &mut Vec<ReadError>) -> Result<(), ReadError> {
for region in [MAIN_BOOT_REGION_SECTOR, BOOT_REGION_SECTORS] {
let covered = self.read_sectors(region, CHECKSUM_SECTOR)?;
let stored_sector = self.read_sectors(region + CHECKSUM_SECTOR, 1)?;
let Some(stored) = checksum_sector_value(&stored_sector) else {
out.push(ReadError::BootChecksumSectorSplit { sector: region });
continue;
};
let computed = boot_checksum(&covered);
if computed != stored {
out.push(ReadError::BootChecksumMismatch {
sector: region,
computed,
stored,
});
}
self.check_extended_boot_sectors(region, &covered, out);
}
let backup = self.read_sectors(BOOT_REGION_SECTORS, 1)?;
match MainBootSector::read_from(&backup) {
Ok(copy) => {
if let Some(detail) = self.backup_differs(©) {
out.push(ReadError::BackupBootRegionDiffers {
sector: BOOT_REGION_SECTORS,
detail,
});
}
}
Err(e) => out.push(ReadError::BackupBootRegionDiffers {
sector: BOOT_REGION_SECTORS,
detail: e.to_string(),
}),
}
Ok(())
}
fn check_extended_boot_sectors(&self, region: u64, covered: &[u8], out: &mut Vec<ReadError>) {
let bytes_per_sector = self.layout.bytes_per_sector as usize;
for n in 0..EXTENDED_BOOT_SECTORS {
let at = (EXTENDED_BOOT_FIRST_SECTOR + n) as usize * bytes_per_sector;
let Some(found) = covered
.get(at..at + bytes_per_sector)
.and_then(extended_boot_signature)
else {
return;
};
if found != EXTENDED_BOOT_SIGNATURE {
out.push(ReadError::BadExtendedBootSignature {
sector: region + EXTENDED_BOOT_FIRST_SECTOR + n,
found,
expected: EXTENDED_BOOT_SIGNATURE,
});
return;
}
}
}
fn backup_differs(&self, copy: &MainBootSector) -> Option<String> {
let main = &self.boot;
let MainBootSector {
jump_boot,
file_system_name,
partition_offset,
volume_length,
fat_offset,
fat_length,
cluster_heap_offset,
cluster_count,
first_cluster_of_root,
volume_serial,
file_system_revision,
volume_flags: _,
bytes_per_sector_shift,
sectors_per_cluster_shift,
number_of_fats,
drive_select,
percent_in_use: _,
boot_code,
} = copy;
let fields: [(&'static str, bool); 15] = [
("JumpBoot", *jump_boot == main.jump_boot),
("FileSystemName", *file_system_name == main.file_system_name),
(
"PartitionOffset",
*partition_offset == main.partition_offset,
),
("VolumeLength", *volume_length == main.volume_length),
("FatOffset", *fat_offset == main.fat_offset),
("FatLength", *fat_length == main.fat_length),
(
"ClusterHeapOffset",
*cluster_heap_offset == main.cluster_heap_offset,
),
("ClusterCount", *cluster_count == main.cluster_count),
(
"FirstClusterOfRootDirectory",
*first_cluster_of_root == main.first_cluster_of_root,
),
("VolumeSerialNumber", *volume_serial == main.volume_serial),
(
"FileSystemRevision",
*file_system_revision == main.file_system_revision,
),
(
"BytesPerSectorShift",
*bytes_per_sector_shift == main.bytes_per_sector_shift,
),
(
"SectorsPerClusterShift",
*sectors_per_cluster_shift == main.sectors_per_cluster_shift,
),
("NumberOfFats", *number_of_fats == main.number_of_fats),
("DriveSelect", *drive_select == main.drive_select),
];
if let Some((field, _)) = fields.iter().find(|(_, same)| !*same) {
return Some(format!("{field} differs from the main region's"));
}
(*boot_code != main.boot_code)
.then(|| "BootCode differs from the main region's".to_string())
}
fn check_volume_state(&self, out: &mut Vec<ReadError>) {
if self.volume_dirty() {
out.push(ReadError::VolumeDirty);
}
if self.media_failure() {
out.push(ReadError::MediaFailure);
}
}
fn check_revision(&self, out: &mut Vec<ReadError>) {
let minor = self.boot.minor_revision();
if minor != FILE_SYSTEM_MINOR_REVISION {
out.push(ReadError::UnknownMinorRevision { minor });
}
}
fn measure_root(&mut self) -> Result<u64, ReadError> {
let start = self.layout.first_cluster_of_root;
let mut clusters = 0u64;
let mut current = start;
loop {
if clusters >= u64::from(self.layout.cluster_count) {
return Err(ReadError::ChainTooLong {
start,
clusters: self.layout.cluster_count,
});
}
clusters += 1;
match self.next_cluster(current)? {
Some(next) => current = next,
None => break,
}
}
Ok(clusters * u64::from(self.layout.bytes_per_cluster))
}
fn load_residents(&mut self, out: &mut Vec<ReadError>) -> Result<(), ReadError> {
let root = self.root();
let mut bitmap: Option<AllocationBitmapEntry> = None;
let mut upcase: Option<UpcaseTableEntry> = None;
let mut label: Option<VolumeLabelEntry> = None;
let mut duplicates: Vec<ReadError> = Vec::new();
self.for_each_slot::<ReadError>(&root, |_, slot| {
let entry_type = slot.entry_type();
if entry_type.is_end_of_directory() {
return Ok(ControlFlow::Break(()));
}
if !entry_type.in_use() || entry_type.is_secondary() {
return Ok(ControlFlow::Continue(()));
}
let mut second = |named: &'static str| {
duplicates.push(ReadError::DuplicateRootEntry {
index: slot.index,
entry_type: named,
});
};
match entry_type {
EntryType::ALLOCATION_BITMAP => match bitmap {
None => bitmap = Some(AllocationBitmapEntry::read_from(&slot.bytes)?),
Some(_) => second("allocation bitmap"),
},
EntryType::UPCASE_TABLE => match upcase {
None => upcase = Some(UpcaseTableEntry::read_from(&slot.bytes)?),
Some(_) => second("up-case table"),
},
EntryType::VOLUME_LABEL => match label {
None => label = Some(VolumeLabelEntry::read_from(&slot.bytes)?),
Some(_) => second("volume label"),
},
_ => {}
}
Ok(ControlFlow::Continue(()))
})?;
out.append(&mut duplicates);
let bitmap = bitmap.ok_or(ReadError::MissingResident {
resident: "allocation bitmap",
})?;
let upcase = upcase.ok_or(ReadError::MissingResident {
resident: "up-case table",
})?;
let want = u64::from(self.layout.cluster_count).div_ceil(8);
if bitmap.data_length != want {
out.push(ReadError::BitmapWrongSize {
bytes: bitmap.data_length,
clusters: self.layout.cluster_count,
});
}
self.bitmap = Resident {
first_cluster: bitmap.first_cluster,
bytes: bitmap.data_length,
};
self.layout.bitmap_cluster = bitmap.first_cluster;
self.layout.bitmap_bytes = bitmap.data_length;
self.layout.upcase_cluster = upcase.first_cluster;
self.layout.upcase_bytes = upcase.data_length;
self.upcase = self.load_upcase(&upcase, out)?;
self.label = label.and_then(|entry| self.label_of(&entry, out));
Ok(())
}
fn label_of(&self, entry: &VolumeLabelEntry, out: &mut Vec<ReadError>) -> Option<Vec<u8>> {
let mut count = usize::from(entry.character_count);
if count > MAX_LABEL_UNITS {
out.push(ReadError::LabelTooLong {
count: entry.character_count,
limit: MAX_LABEL_UNITS,
});
count = MAX_LABEL_UNITS;
}
if count == 0 {
return None;
}
let units = &entry.label[..count];
if units.contains(&0) {
out.push(ReadError::LabelNulUnit);
return None;
}
Some(decode_utf16(units).0)
}
fn load_upcase(
&mut self,
entry: &UpcaseTableEntry,
out: &mut Vec<ReadError>,
) -> Result<UpcaseTable, ReadError> {
if entry.data_length > MAX_UPCASE_BYTES {
out.push(ReadError::UpcaseTooLong {
bytes: entry.data_length,
limit: MAX_UPCASE_BYTES,
});
return Ok(UpcaseTable::new(&[]));
}
let bytes = self.read_chain(entry.first_cluster, entry.data_length)?;
let computed = upcase_checksum(&bytes);
if computed != entry.table_checksum {
out.push(ReadError::UpcaseChecksumMismatch {
computed,
stored: entry.table_checksum,
});
}
let units: Vec<u16> = (0..bytes.len() / 2)
.map(|n| get_u16(&bytes, n * 2))
.collect();
Ok(UpcaseTable::new(&units))
}
fn read_sectors(&mut self, first: u64, count: u64) -> Result<Vec<u8>, ReadError> {
let out_of_range = || ReadError::BadBootSector {
detail: format!("sector {first} is past the volume's {} sectors", {
self.layout.volume_length
}),
};
let end = first
.checked_add(count)
.filter(|end| *end <= self.layout.volume_length)
.ok_or_else(out_of_range)?;
debug_assert!(end <= self.layout.volume_length);
let bytes_per_sector = u64::from(self.layout.bytes_per_sector);
let offset = offset_of(self.base, first, bytes_per_sector).ok_or_else(out_of_range)?;
let len = usize::try_from(count * bytes_per_sector).map_err(|_| out_of_range())?;
Ok(read_exact_at(&mut self.src, offset, len)?)
}
fn read_cluster(&mut self, n: u32) -> Result<Vec<u8>, ReadError> {
let first = self
.layout
.cluster_start_sector(n)
.ok_or(ReadError::ClusterOutOfRange { cluster: n })?;
self.read_sectors(first, u64::from(self.layout.sectors_per_cluster()))
}
fn table_entry(&mut self, cluster: u32) -> Result<u32, ReadError> {
if cluster < FIRST_CLUSTER || cluster - FIRST_CLUSTER >= self.layout.cluster_count {
return Err(ReadError::ClusterOutOfRange { cluster });
}
let bytes_per_sector = u64::from(self.layout.bytes_per_sector);
let offset = u64::from(cluster) * 4;
let sector = u64::from(self.layout.fat_offset) + offset / bytes_per_sector;
let within = (offset % bytes_per_sector) as usize;
let stale = match &self.fat_window {
Some((at, _)) => *at != sector,
None => true,
};
if stale {
let buf = self.read_sectors(sector, 1)?;
self.fat_window = Some((sector, buf));
}
let (_, buf) = self.fat_window.as_ref().expect("just loaded");
if within + 4 > buf.len() {
return Err(ReadError::ClusterOutOfRange { cluster });
}
Ok(get_u32(buf, within))
}
fn is_allocated(&mut self, cluster: u32) -> Result<bool, ReadError> {
if cluster < FIRST_CLUSTER || cluster - FIRST_CLUSTER >= self.layout.cluster_count {
return Err(ReadError::ClusterOutOfRange { cluster });
}
let bit = u64::from(cluster - FIRST_CLUSTER);
let at = bit / 8;
if at >= self.bitmap.bytes {
return Ok(false);
}
let bytes_per_cluster = u64::from(self.layout.bytes_per_cluster);
let bytes_per_sector = u64::from(self.layout.bytes_per_sector);
let index = at / bytes_per_cluster;
let holding = match self.bitmap_at {
Some((cached, cluster)) if cached == index => cluster,
_ => {
let Some(holding) = self.chain_cluster(self.bitmap.first_cluster, index)? else {
return Err(ReadError::StreamTooShort {
start: self.bitmap.first_cluster,
declared: self.bitmap.bytes,
held: index * bytes_per_cluster,
});
};
self.bitmap_at = Some((index, holding));
holding
}
};
let within_cluster = at % bytes_per_cluster;
let Some(cluster_sector) = self.layout.cluster_start_sector(holding) else {
return Err(ReadError::ClusterOutOfRange { cluster: holding });
};
let sector = cluster_sector + within_cluster / bytes_per_sector;
let within = (within_cluster % bytes_per_sector) as usize;
let stale = match &self.bitmap_window {
Some((cached, _)) => *cached != sector,
None => true,
};
if stale {
let buf = self.read_sectors(sector, 1)?;
self.bitmap_window = Some((sector, buf));
}
let (_, buf) = self.bitmap_window.as_ref().expect("just loaded");
let byte = buf.get(within).copied().unwrap_or(0);
Ok(byte & (1 << (bit % 8)) != 0)
}
fn next_cluster(&mut self, cluster: u32) -> Result<Option<u32>, ReadError> {
let entry = self.table_entry(cluster)?;
if entry == super::ondisk::END_OF_CHAIN {
return Ok(None);
}
if entry == BAD_CLUSTER {
return Err(ReadError::BadClusterInChain { cluster: entry });
}
if entry < FIRST_CLUSTER || entry - FIRST_CLUSTER >= self.layout.cluster_count {
return Err(ReadError::BadChainEntry { cluster, entry });
}
Ok(Some(entry))
}
fn chain_cluster(&mut self, start: u32, index: u64) -> Result<Option<u32>, ReadError> {
if start < FIRST_CLUSTER || start - FIRST_CLUSTER >= self.layout.cluster_count {
return Err(ReadError::ClusterOutOfRange { cluster: start });
}
let (mut at, mut current) = match self.chain_cursor {
Some((cursor_start, cursor_index, cursor_cluster))
if cursor_start == start && cursor_index <= index =>
{
(cursor_index, cursor_cluster)
}
_ => (0, start),
};
while at < index {
match self.next_cluster(current)? {
Some(next) => {
current = next;
at += 1;
}
None => return Ok(None),
}
if at > u64::from(self.layout.cluster_count) {
return Err(ReadError::ChainTooLong {
start,
clusters: self.layout.cluster_count,
});
}
}
self.chain_cursor = Some((start, at, current));
Ok(Some(current))
}
fn stream_cluster(&mut self, storage: Storage, index: u64) -> Result<Option<u32>, ReadError> {
match storage {
Storage::None => Ok(None),
Storage::Contiguous(first) => {
let n = u64::from(first) + index;
match u32::try_from(n) {
Ok(n)
if n >= FIRST_CLUSTER && n - FIRST_CLUSTER < self.layout.cluster_count =>
{
Ok(Some(n))
}
_ => Err(ReadError::ClusterOutOfRange {
cluster: u32::try_from(n).unwrap_or(u32::MAX),
}),
}
}
Storage::Chain(start) => self.chain_cluster(start, index),
}
}
fn read_chain(&mut self, first: u32, len: u64) -> Result<Vec<u8>, ReadError> {
let bytes_per_cluster = u64::from(self.layout.bytes_per_cluster);
let mut out = Vec::new();
let mut index = 0u64;
while (out.len() as u64) < len {
let Some(cluster) = self.chain_cluster(first, index)? else {
return Err(ReadError::StreamTooShort {
start: first,
declared: len,
held: index * bytes_per_cluster,
});
};
let bytes = self.read_cluster(cluster)?;
let take = bytes.len().min((len - out.len() as u64) as usize);
out.extend_from_slice(&bytes[..take]);
index += 1;
}
Ok(out)
}
fn for_each_slot<E: From<ReadError>>(
&mut self,
node: &Node,
mut visit: impl FnMut(&mut Self, Slot) -> Result<ControlFlow<()>, E>,
) -> Result<(), E> {
let Some(start) = node.storage.first_cluster() else {
return Ok(());
};
let bytes_per_cluster = u64::from(self.layout.bytes_per_cluster);
let slots_per_sector = u64::from(self.layout.bytes_per_sector) / DIR_ENTRY_SIZE as u64;
let clusters = node.data_length.div_ceil(bytes_per_cluster.max(1));
let mut index = 0u32;
let mut visited = ClusterSet::new(self.layout.cluster_count);
visited.insert(start);
let mut current = Some(start);
for at in 0..clusters {
let Some(cluster) = current else {
return Err(E::from(ReadError::StreamTooShort {
start,
declared: node.data_length,
held: at * bytes_per_cluster,
}));
};
let first_sector = self
.layout
.cluster_start_sector(cluster)
.ok_or(ReadError::ClusterOutOfRange { cluster })?;
let bytes = self.read_cluster(cluster).map_err(E::from)?;
for (i, chunk) in bytes.as_chunks::<DIR_ENTRY_SIZE>().0.iter().enumerate() {
let slot = Slot {
bytes: *chunk,
index,
cluster,
sector: first_sector + (i as u64) / slots_per_sector.max(1),
};
index = index.saturating_add(1);
if visit(self, slot)?.is_break() {
return Ok(());
}
}
if at + 1 == clusters {
break;
}
current = match node.storage {
Storage::Contiguous(_) | Storage::None => {
self.stream_cluster(node.storage, at + 1).map_err(E::from)?
}
Storage::Chain(_) => match self.next_cluster(cluster).map_err(E::from)? {
None => None,
Some(following) => {
if !visited.insert(following) {
return Err(E::from(ReadError::ChainTooLong {
start,
clusters: self.layout.cluster_count,
}));
}
Some(following)
}
},
};
}
Ok(())
}
pub fn read_dir(&mut self, node: &Node) -> Result<Vec<Entry>, ReadError> {
let policy = self.policy;
self.parse_dir(node, &mut OnDeviation::Policy(policy))
}
fn parse_dir(
&mut self,
node: &Node,
deviations: &mut OnDeviation<'_>,
) -> Result<Vec<Entry>, ReadError> {
if !node.is_dir() {
return Err(ReadError::NotADirectory { path: Vec::new() });
}
let is_root = node.times.is_none();
let cap = self.limits.max_walk_entries.min(self.max_names());
let mut out: Vec<Entry> = Vec::new();
let mut set: Option<PendingSet> = None;
let mut ended: Option<u32> = None;
let mut reported_after_end = false;
let mut too_many = false;
self.for_each_slot::<ReadError>(node, |reader, slot| {
let at = slot.location();
let entry_type = slot.entry_type();
if let Some(marker) = ended {
if slot.cluster != marker {
return Ok(ControlFlow::Break(()));
}
if !entry_type.is_end_of_directory() && !reported_after_end {
deviations.record(at, ReadError::EntriesAfterEnd { index: slot.index })?;
reported_after_end = true;
}
return Ok(ControlFlow::Continue(()));
}
if let Some(pending) = set.as_mut() {
if entry_type.in_use() && entry_type.is_secondary() {
pending.push(&slot.bytes);
if pending.is_complete() {
let finished = set.take().expect("just checked");
if let Some(entry) = reader.finish_set(finished, deviations)? {
out.push(entry);
}
}
return Ok(ControlFlow::Continue(()));
}
let broken = set.take().expect("just checked");
deviations.record(
Location::at_entry(broken.index),
ReadError::IncompleteEntrySet {
index: broken.index,
detail: format!(
"it declares {} entries behind it and {} follow",
broken.want,
broken.have()
),
},
)?;
}
if entry_type.is_end_of_directory() {
ended = Some(slot.cluster);
return Ok(ControlFlow::Continue(()));
}
if !entry_type.in_use() {
return Ok(ControlFlow::Continue(()));
}
if entry_type.is_secondary() {
deviations.record(at, ReadError::StraySecondaryEntry { index: slot.index })?;
return Ok(ControlFlow::Continue(()));
}
match entry_type {
EntryType::FILE => {
if out.len() >= cap {
too_many = true;
return Ok(ControlFlow::Break(()));
}
let file = FileEntry::read_from(&slot.bytes)?;
if file.secondary_count == 0 {
deviations.record(
at,
ReadError::IncompleteEntrySet {
index: slot.index,
detail: "it declares no entries behind it, and a file needs a \
stream extension and a name"
.to_string(),
},
)?;
return Ok(ControlFlow::Continue(()));
}
set = Some(PendingSet::new(
slot.index,
file.secondary_count,
&slot.bytes,
));
}
EntryType::ALLOCATION_BITMAP
| EntryType::UPCASE_TABLE
| EntryType::VOLUME_LABEL => {
if !is_root {
let named = match entry_type {
EntryType::ALLOCATION_BITMAP => "allocation bitmap",
EntryType::UPCASE_TABLE => "up-case table",
_ => "volume label",
};
deviations.record(
at,
ReadError::MisplacedRootEntry {
index: slot.index,
entry_type: named,
},
)?;
}
}
other if other.is_benign() => {
}
other => {
deviations.record(
at,
ReadError::UnknownCriticalEntry {
index: slot.index,
entry_type: other.0,
},
)?;
}
}
Ok(ControlFlow::Continue(()))
})?;
if too_many {
return Err(ReadError::WalkTooLarge { limit: cap });
}
if let Some(unfinished) = set {
deviations.record(
Location::at_entry(unfinished.index),
ReadError::IncompleteEntrySet {
index: unfinished.index,
detail: format!(
"it declares {} entries behind it and the directory ends after {}",
unfinished.want,
unfinished.have()
),
},
)?;
}
Ok(out)
}
fn finish_set(
&mut self,
set: PendingSet,
deviations: &mut OnDeviation<'_>,
) -> Result<Option<Entry>, ReadError> {
let at = Location::at_entry(set.index);
let index = set.index;
let computed = entry_set_checksum(&set.bytes);
let file = FileEntry::read_from(&set.bytes)?;
if computed != file.set_checksum {
deviations.record(
at,
ReadError::SetChecksumMismatch {
index,
computed,
stored: file.set_checksum,
},
)?;
}
let Some(stream_bytes) = set.bytes.get(DIR_ENTRY_SIZE..2 * DIR_ENTRY_SIZE) else {
deviations.record(
at,
ReadError::IncompleteEntrySet {
index,
detail: "it holds no stream extension".to_string(),
},
)?;
return Ok(None);
};
let Ok(stream) = StreamExtensionEntry::read_from(stream_bytes) else {
deviations.record(
at,
ReadError::IncompleteEntrySet {
index,
detail: "its first secondary entry is not a stream extension".to_string(),
},
)?;
return Ok(None);
};
let mut units: Vec<u16> = Vec::new();
for slot in set.bytes[2 * DIR_ENTRY_SIZE..]
.as_chunks::<DIR_ENTRY_SIZE>()
.0
{
let entry_type = EntryType(slot[0]);
if entry_type == EntryType::FILE_NAME {
let name = FileNameEntry::read_from(slot)?;
units.extend_from_slice(&name.units);
} else if !entry_type.is_benign() {
deviations.record(
at,
ReadError::UnknownCriticalEntry {
index,
entry_type: entry_type.0,
},
)?;
}
}
let want = usize::from(stream.name_length);
if units.len() < want {
deviations.record(
at,
ReadError::IncompleteEntrySet {
index,
detail: format!(
"its name is {want} code units and its entries carry {}",
units.len()
),
},
)?;
return Ok(None);
}
let carried = units.len() / NAME_UNITS_PER_ENTRY;
let needed = want.div_ceil(NAME_UNITS_PER_ENTRY);
if carried > needed {
deviations.record(
at,
ReadError::ExcessNameEntries {
index,
want: needed,
have: carried,
},
)?;
}
units.truncate(want);
let computed = name_hash(&self.upcase.fold(&units));
if computed != stream.name_hash {
deviations.record(
at,
ReadError::NameHashMismatch {
index,
computed,
stored: stream.name_hash,
},
)?;
}
let (name, well_formed) = decode_utf16(&units);
if !well_formed {
deviations.record(at, ReadError::IllFormedName { index })?;
}
if is_hostile_component(&name) {
deviations.record(at, ReadError::HostileName { index })?;
return Ok(None);
}
let node = self.node_of(&file, &stream, index, deviations)?;
Ok(Some(Entry { name, node }))
}
fn node_of(
&mut self,
file: &FileEntry,
stream: &StreamExtensionEntry,
index: u32,
deviations: &mut OnDeviation<'_>,
) -> Result<Node, ReadError> {
let at = Location::at_entry(index);
let is_dir = file.attributes.contains(FileAttributes::DIRECTORY);
let reserved = file.attributes.bits() & !FileAttributes::DEFINED.bits();
if reserved != 0 {
deviations.record(
at,
ReadError::ReservedAttributes {
index,
bits: reserved,
},
)?;
}
self.check_times(file, index, deviations)?;
let storage = if stream.first_cluster == 0 || stream.data_length == 0 {
if stream.first_cluster == 0 && stream.data_length != 0 {
deviations.record(
at,
ReadError::StreamWithoutAllocation {
index,
declared: stream.data_length,
},
)?;
}
if stream.first_cluster != 0 && stream.data_length == 0 {
deviations.record(
at,
ReadError::AllocationWithoutLength {
index,
first_cluster: stream.first_cluster,
},
)?;
}
if is_dir {
deviations.record(at, ReadError::DirectoryWithoutAllocation { index })?;
}
Storage::None
} else {
if stream.flags & SECONDARY_ALLOCATION_POSSIBLE == 0 {
deviations.record(at, ReadError::AllocationNotPossible { index })?;
}
if stream.no_fat_chain() {
Storage::Contiguous(stream.first_cluster)
} else {
Storage::Chain(stream.first_cluster)
}
};
let declared = self.bound_length(stream.data_length, is_dir, index, deviations)?;
let mut valid = stream.valid_data_length;
if valid > declared {
deviations.record(at, ReadError::ValidLengthPastEnd { valid, declared })?;
valid = declared;
} else if valid < declared {
deviations.record(at, ReadError::ValidLengthTrails { valid, declared })?;
}
Ok(Node {
storage,
attributes: file.attributes,
data_length: declared,
valid_data_length: valid,
times: Some(times_of(file)),
})
}
fn bound_length(
&self,
declared: u64,
is_dir: bool,
index: u32,
deviations: &mut OnDeviation<'_>,
) -> Result<u64, ReadError> {
let at = Location::at_entry(index);
let mut declared = declared;
let heap = self.layout.heap_bytes();
if declared > heap {
deviations.record(
at,
ReadError::StreamPastHeap {
declared,
limit: heap,
},
)?;
declared = heap;
}
if is_dir {
if declared > MAX_DIRECTORY_BYTES {
deviations.record(
at,
ReadError::DirectoryTooLong {
index,
declared,
limit: MAX_DIRECTORY_BYTES,
},
)?;
declared = MAX_DIRECTORY_BYTES;
}
let bytes_per_cluster = self.layout.bytes_per_cluster;
if !declared.is_multiple_of(u64::from(bytes_per_cluster)) {
deviations.record(
at,
ReadError::DirectoryLengthNotClusters {
index,
declared,
bytes_per_cluster,
},
)?;
}
}
Ok(declared)
}
fn check_times(
&self,
file: &FileEntry,
index: u32,
deviations: &mut OnDeviation<'_>,
) -> Result<(), ReadError> {
let at = Location::at_entry(index);
for (field, packed, tenth) in [
("creation time", file.create, file.create_tenth),
("modification time", file.modify, file.modify_tenth),
("access time", file.access, 0),
] {
if !unpack_timestamp(packed, tenth).is_well_formed() {
deviations.record(at, ReadError::MalformedTimestamp { index, field })?;
}
}
Ok(())
}
pub fn lookup(&mut self, path: &[u8]) -> Result<Node, ReadError> {
crate::resolve::drive(self, path, true)
}
fn fold_name(&self, name: &[u8]) -> Vec<u16> {
match core::str::from_utf8(name) {
Ok(text) => self.upcase.fold(&text.encode_utf16().collect::<Vec<_>>()),
Err(_) => Vec::new(),
}
}
pub fn read_into(
&mut self,
node: &Node,
offset: u64,
buf: &mut [u8],
) -> Result<usize, ReadError> {
if node.is_dir() {
return Ok(0);
}
let size = node.data_length;
if offset >= size || buf.is_empty() {
return Ok(0);
}
let bytes_per_cluster = u64::from(self.layout.bytes_per_cluster);
let want = buf.len().min((size - offset) as usize);
let mut done = 0usize;
while done < want {
let at = offset + done as u64;
if at >= node.valid_data_length {
buf[done..want].fill(0);
return Ok(want);
}
let take = (want - done).min((node.valid_data_length - at) as usize);
let index = at / bytes_per_cluster;
let within = (at % bytes_per_cluster) as usize;
let Some(cluster) = self.stream_cluster(node.storage, index)? else {
return Err(ReadError::StreamTooShort {
start: node.storage.first_cluster().unwrap_or(0),
declared: size,
held: index * bytes_per_cluster,
});
};
let bytes = self.read_cluster(cluster)?;
let take = take.min(bytes.len() - within);
buf[done..done + take].copy_from_slice(&bytes[within..within + take]);
done += take;
}
Ok(done)
}
fn whole_file_len(&self, node: &Node) -> Result<u64, ReadError> {
if node.data_length > self.limits.max_file_bytes {
return Err(ReadError::FileTooLarge {
size: node.data_length,
limit: self.limits.max_file_bytes,
});
}
Ok(node.data_length)
}
pub fn read_data_to(&mut self, node: &Node, mut out: impl Write) -> Result<u64, ReadError> {
if node.is_dir() {
return Ok(0);
}
let size = self.whole_file_len(node)?;
let mut buf = vec![0u8; self.layout.bytes_per_cluster as usize];
let mut done = 0u64;
while done < size {
let want = buf.len().min((size - done) as usize);
let got = self.read_into(node, done, &mut buf[..want])?;
if got == 0 {
return Err(ReadError::StreamTooShort {
start: node.storage.first_cluster().unwrap_or(0),
declared: size,
held: done,
});
}
out.write_all(&buf[..got])?;
done += got as u64;
}
Ok(done)
}
pub fn read_data(&mut self, node: &Node) -> Result<Vec<u8>, ReadError> {
let mut out = Vec::new();
self.read_data_to(node, &mut out)?;
Ok(out)
}
pub fn walk(&mut self) -> Result<Vec<WalkEntry>, ReadError> {
let mut out = Vec::new();
self.walk_with::<ReadError>(|_, entry| {
out.push(entry);
Ok(())
})?;
Ok(out)
}
pub fn walk_with<E: From<ReadError>>(
&mut self,
mut visit: impl FnMut(&mut Self, WalkEntry) -> Result<(), E>,
) -> Result<(), E> {
crate::walk::drive(self, |reader, entry| visit(reader, entry))
}
fn walk_children(&mut self, node: &Node, prefix: &[u8]) -> Result<Vec<WalkEntry>, ReadError> {
let mut entries = self.read_dir(node)?;
entries.sort_by(|a, b| a.name.cmp(&b.name));
let mut children = Vec::new();
for e in entries.iter().rev() {
let path = crate::walk::child_path(prefix, &e.name)
.ok_or(ReadError::PathTooLong { limit: MAX_PATH })?;
children.push(WalkEntry { path, node: e.node });
}
Ok(children)
}
fn max_names(&self) -> usize {
let slots = u64::from(self.layout.cluster_count) * u64::from(self.layout.bytes_per_cluster)
/ DIR_ENTRY_SIZE as u64;
usize::try_from(slots / 3).unwrap_or(usize::MAX)
}
#[must_use]
pub fn scan(&mut self) -> ScanReport {
let mut findings = Findings::new(self.limits.max_findings);
for anomaly in self.open_anomalies.clone() {
findings.push(anomaly);
}
self.scan_table_head(&mut findings);
let reached = self.scan_tree(&mut findings);
if let Some(reached) = reached {
self.scan_allocation(&mut findings, &reached);
}
findings.into_report(self.layout.bytes_per_sector)
}
fn scan_table_head(&mut self, findings: &mut Findings<Anomaly>) {
for (index, expected) in [(0u32, FAT_ENTRY_MEDIA), (1, FAT_ENTRY_RESERVED)] {
let bytes_per_sector = u64::from(self.layout.bytes_per_sector);
let offset = u64::from(index) * 4;
let sector = u64::from(self.layout.fat_offset) + offset / bytes_per_sector;
let within = (offset % bytes_per_sector) as usize;
let found = match self.read_sectors(sector, 1) {
Ok(buf) if within + 4 <= buf.len() => get_u32(&buf, within),
Ok(_) => continue,
Err(e) => {
findings.push(e.anomaly());
return;
}
};
if found != expected {
findings.push(
ReadError::BadReservedEntry {
index,
found,
expected,
}
.anomaly(),
);
}
}
}
fn scan_tree(&mut self, findings: &mut Findings<Anomaly>) -> Option<ClusterSet> {
let mut reached = ClusterSet::new(self.layout.cluster_count);
let residents = [
(self.bitmap.first_cluster, self.bitmap.bytes),
(self.layout.upcase_cluster, self.layout.upcase_bytes),
(self.layout.first_cluster_of_root, self.root_bytes),
];
for (first, bytes) in residents {
self.claim_stream(Storage::Chain(first), bytes, &[], &mut reached, findings);
}
let mut visited = ClusterSet::new(self.layout.cluster_count);
visited.insert(self.layout.first_cluster_of_root);
let mut queue = vec![(Vec::new(), self.root())];
let mut names = 0usize;
let cap = self.limits.max_walk_entries.min(self.max_names());
while let Some((path, node)) = queue.pop() {
if findings.is_full() {
return None;
}
if node.is_dir() {
if !path.is_empty() {
self.claim_stream(
node.storage,
node.data_length,
&path,
&mut reached,
findings,
);
}
let mut deviations = OnDeviation::Collect(findings);
let entries = match self.parse_dir(&node, &mut deviations) {
Ok(entries) => entries,
Err(e @ ReadError::WalkTooLarge { .. }) => {
findings.push(e.anomaly());
return None;
}
Err(e) => {
findings.push(e.anomaly());
continue;
}
};
for entry in entries {
names += 1;
if names > cap {
findings.push(ReadError::WalkTooLarge { limit: cap }.anomaly());
return None;
}
let mut child = path.clone();
child.push(b'/');
child.extend_from_slice(&entry.name);
let descend = match entry.node.storage {
Storage::None => false,
Storage::Contiguous(first) | Storage::Chain(first) => {
!entry.node.is_dir() || visited.insert(first)
}
};
if descend {
queue.push((child, entry.node));
}
}
} else {
self.claim_stream(
node.storage,
node.data_length,
&path,
&mut reached,
findings,
);
}
}
Some(reached)
}
fn claim_stream(
&mut self,
storage: Storage,
bytes: u64,
path: &[u8],
reached: &mut ClusterSet,
findings: &mut Findings<Anomaly>,
) {
let Some(start) = storage.first_cluster() else {
return;
};
let bytes_per_cluster = u64::from(self.layout.bytes_per_cluster);
let clusters = bytes.div_ceil(bytes_per_cluster.max(1));
let mut own = std::collections::HashSet::new();
for index in 0..clusters {
let cluster = match self.stream_cluster(storage, index) {
Ok(Some(cluster)) => cluster,
Ok(None) => {
findings.push(
ReadError::StreamTooShort {
start,
declared: bytes,
held: index * bytes_per_cluster,
}
.anomaly(),
);
return;
}
Err(e) => {
let mut anomaly = e.anomaly();
if !path.is_empty() {
anomaly.detail =
format!("{}: {}", crate::escape::printable(path), anomaly.detail);
}
findings.push(anomaly);
return;
}
};
if !reached.insert(cluster) {
let mut anomaly = ReadError::CrossLinkedCluster { cluster }.anomaly();
if own.contains(&cluster) {
anomaly.detail = format!(
"the chain from cluster {start} returns to cluster {cluster}, and a \
chain that loops never ends"
);
}
if !path.is_empty() {
anomaly.detail =
format!("{}: {}", crate::escape::printable(path), anomaly.detail);
}
findings.push(anomaly);
return;
}
own.insert(cluster);
match self.is_allocated(cluster) {
Ok(true) => {}
Ok(false) => findings.push(ReadError::ClusterNotAllocated { cluster }.anomaly()),
Err(e) => {
findings.push(e.anomaly());
return;
}
}
if findings.is_full() {
return;
}
}
}
fn scan_allocation(&mut self, findings: &mut Findings<Anomaly>, reached: &ClusterSet) {
let mut lost = 0u64;
let mut first_lost = None;
let mut in_use = 0u64;
for n in 0..self.layout.cluster_count {
let cluster = FIRST_CLUSTER + n;
let allocated = match self.is_allocated(cluster) {
Ok(allocated) => allocated,
Err(e) => {
findings.push(e.anomaly());
return;
}
};
if allocated {
in_use += 1;
if !reached.contains(cluster) {
lost += 1;
first_lost.get_or_insert(cluster);
}
}
}
if let Some(first) = first_lost {
findings.push(ReadError::LostClusters { count: lost, first }.anomaly());
}
let stated = self.boot.percent_in_use;
let actual = percent_in_use(
u32::try_from(in_use).unwrap_or(u32::MAX),
self.layout.cluster_count,
);
if stated > PERCENT_IN_USE_MAX && stated != PERCENT_IN_USE_UNKNOWN {
findings.push(ReadError::PercentInUseOutOfRange { stated }.anomaly());
} else if stated != actual && stated != PERCENT_IN_USE_UNKNOWN {
findings.push(
ReadError::PercentInUseStale {
stated,
in_use,
clusters: self.layout.cluster_count,
actual,
}
.anomaly(),
);
}
}
}
impl<R: Read + Seek> crate::resolve::Resolve for Reader<R> {
type Ancestor = Node;
type Node = Node;
type Error = ReadError;
fn root_node(&mut self) -> Result<Node, ReadError> {
Ok(self.root())
}
fn ancestor_of(&self, node: &Node) -> Node {
*node
}
fn node_at(&mut self, ancestor: Node) -> Result<Node, ReadError> {
Ok(ancestor)
}
fn is_directory(&self, node: &Node) -> bool {
node.is_dir()
}
fn find_name(&mut self, dir: &Node, name: &[u8]) -> Result<Option<Node>, ReadError> {
let entries = self.read_dir(dir)?;
let folded = self.fold_name(name);
let mut fallback = None;
for e in &entries {
if e.name == name {
return Ok(Some(e.node));
}
if fallback.is_none() && self.fold_name(&e.name) == folded {
fallback = Some(e.node);
}
}
Ok(fallback)
}
fn not_found(&self, path: &[u8]) -> ReadError {
ReadError::NotFound {
path: path.to_vec(),
}
}
fn not_a_directory(&self, _node: &Node, path: &[u8]) -> ReadError {
ReadError::NotADirectory {
path: path.to_vec(),
}
}
}
impl<R: Read + Seek> crate::walk::Walk for Reader<R> {
type Pending = WalkEntry;
type Entry = WalkEntry;
type Key = u32;
type Error = ReadError;
fn cap(&mut self) -> usize {
self.limits.max_walk_entries.min(self.max_names())
}
fn seed(&mut self) -> Result<crate::walk::Seed<Self>, ReadError> {
let root = self.root();
let occupied = root.storage.first_cluster().into_iter().collect();
Ok((self.walk_children(&root, &[])?, occupied))
}
fn resolve(&mut self, pending: WalkEntry) -> Result<WalkEntry, ReadError> {
Ok(pending)
}
fn descend_key(&self, entry: &WalkEntry) -> Option<u32> {
entry
.node
.is_dir()
.then(|| entry.node.storage.first_cluster())?
}
fn children(&mut self, entry: &WalkEntry) -> Result<Vec<WalkEntry>, ReadError> {
self.walk_children(&entry.node, &entry.path)
}
fn too_large(limit: usize) -> ReadError {
ReadError::WalkTooLarge { limit }
}
}
impl<R: Read + Seek> FsTree for Reader<R> {
type Node = Node;
fn family(&self) -> Family {
Family::ExFat
}
fn max_file_bytes(&self) -> u64 {
self.limits.max_file_bytes
}
fn walk_tree<E, F>(&mut self, mut visit: F) -> Result<(), E>
where
E: From<TreeError>,
F: FnMut(&mut Self, TreeEntry<Node>) -> Result<(), E>,
{
let root = self.root();
visit(self, TreeEntry::new(Vec::new(), NodeKind::Directory, root))?;
let outcome = self.walk_with::<WalkFail<E>>(|reader, entry| {
let kind = if entry.node.is_dir() {
NodeKind::Directory
} else {
NodeKind::File {
size: entry.node.data_length,
}
};
visit(reader, TreeEntry::new(entry.path, kind, entry.node)).map_err(WalkFail::Visitor)
});
match outcome {
Ok(()) => Ok(()),
Err(WalkFail::Read(e)) => Err(E::from(TreeError::from(e))),
Err(WalkFail::Tree(e)) => Err(E::from(e)),
Err(WalkFail::Visitor(e)) => Err(e),
}
}
fn stat(&mut self, node: &Node, synthesis: &Synthesis) -> Result<Attributes, TreeError> {
Ok(Attributes::from_read_only_bit(
synthesis,
node.is_dir(),
node.attributes.contains(FileAttributes::READ_ONLY),
node.times.map(|t| (t.access, t.modify)),
))
}
fn read_bytes(&mut self, node: &Node, offset: u64, buf: &mut [u8]) -> Result<usize, TreeError> {
Ok(Reader::read_into(self, node, offset, buf)?)
}
fn link_target(&mut self, _node: &Node) -> Result<Vec<u8>, TreeError> {
Err(TreeError::Malformed {
family: Family::ExFat,
detail: "an exFAT volume holds no symbolic links".to_string(),
})
}
}
type WalkFail<E> = crate::tree::WalkFail<ReadError, E>;
impl<E> From<ReadError> for WalkFail<E> {
fn from(err: ReadError) -> Self {
WalkFail::Read(err)
}
}
struct PendingSet {
index: u32,
want: usize,
bytes: Vec<u8>,
}
impl PendingSet {
fn new(index: u32, secondary: u8, file: &[u8; DIR_ENTRY_SIZE]) -> Self {
let want = usize::from(secondary);
let mut bytes = Vec::with_capacity((want + 1) * DIR_ENTRY_SIZE);
bytes.extend_from_slice(file);
Self { index, want, bytes }
}
fn push(&mut self, entry: &[u8; DIR_ENTRY_SIZE]) {
self.bytes.extend_from_slice(entry);
}
fn have(&self) -> usize {
self.bytes.len() / DIR_ENTRY_SIZE - 1
}
fn is_complete(&self) -> bool {
self.have() >= self.want
}
}
struct ClusterSet {
bits: Vec<u64>,
clusters: u32,
}
impl ClusterSet {
fn new(clusters: u32) -> Self {
let highest = clusters as usize + FIRST_CLUSTER as usize;
Self {
bits: vec![0u64; highest.div_ceil(64)],
clusters,
}
}
fn holds(&self, cluster: u32) -> bool {
cluster >= FIRST_CLUSTER && cluster - FIRST_CLUSTER < self.clusters
}
fn insert(&mut self, cluster: u32) -> bool {
if !self.holds(cluster) {
return true;
}
let (word, bit) = (cluster as usize / 64, cluster as usize % 64);
let was = self.bits[word] & (1 << bit) != 0;
self.bits[word] |= 1 << bit;
!was
}
fn contains(&self, cluster: u32) -> bool {
self.holds(cluster)
&& self.bits[cluster as usize / 64] & (1 << (cluster as usize % 64)) != 0
}
}
fn times_of(file: &FileEntry) -> Times {
let at = |field: u32, tenth: u8, offset: u8| {
let minutes = utc_offset_minutes(offset);
let local = unpack_timestamp(field, tenth).decode();
let secs = local
.secs
.saturating_sub(i64::from(minutes.unwrap_or(0)) * 60);
(
Timestamp {
secs,
nanos: local.nanos,
},
minutes,
)
};
let (create, create_offset) = at(file.create, file.create_tenth, file.create_utc_offset);
let (modify, modify_offset) = at(file.modify, file.modify_tenth, file.modify_utc_offset);
let (access, access_offset) = at(file.access, 0, file.access_utc_offset);
Times {
create,
access,
modify,
create_offset,
access_offset,
modify_offset,
}
}
fn decode_utf16(units: &[u16]) -> (Vec<u8>, bool) {
let mut out = String::with_capacity(units.len());
let mut well_formed = true;
for ch in char::decode_utf16(units.iter().copied()) {
match ch {
Ok(ch) => out.push(ch),
Err(_) => {
well_formed = false;
out.push(char::REPLACEMENT_CHARACTER);
}
}
}
(out.into_bytes(), well_formed)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::exfat::ondisk::{
BOOT_CHECKSUM_SKIPS, RECOMMENDED_UPCASE_TABLE, SECONDARY_NO_FAT_CHAIN, UTC_OFFSET,
UTC_OFFSET_VALID, write_checksum_sector, write_upcase_table,
};
use crate::exfat::{FormatOptions, VolumeLabel, format};
use crate::fidelity::Property;
use crate::finding::Finding;
use crate::source::{Metadata, TreeBuilder};
use crate::time::DosTimestamp;
use std::io::Cursor;
const TIME: Timestamp = Timestamp {
secs: 1_426_325_212,
nanos: 0,
};
const VOLUME: u64 = 64 << 20;
fn meta(mode: u16) -> Metadata {
Metadata::new(mode, TIME)
}
fn tree() -> TreeBuilder {
TreeBuilder::new()
.directory(b"/DCIM".to_vec(), meta(0o755))
.file(b"/DCIM/READY.TXT".to_vec(), b"hello\n", meta(0o644))
.file(b"/DCIM/EMPTY.BIN".to_vec(), b"", meta(0o644))
.file(
b"/DCIM/A name long enough to need two entries.txt".to_vec(),
b"two",
meta(0o444),
)
.file(b"/BIG.BIN".to_vec(), vec![0x5a; 9_000], meta(0o644))
}
fn image_of(source: TreeBuilder) -> Vec<u8> {
format(source, VOLUME, FormatOptions::new(0x1234_5678))
.expect("format")
.into_bytes()
}
fn image() -> Vec<u8> {
image_of(tree())
}
fn reader(bytes: &[u8]) -> Reader<Cursor<&[u8]>> {
Reader::open(Cursor::new(bytes)).expect("open")
}
fn lenient(bytes: &[u8]) -> Reader<Cursor<&[u8]>> {
Reader::open_with(
Cursor::new(bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open leniently")
}
fn open_err(bytes: &[u8], policy: ReadPolicy) -> ReadError {
match Reader::open_with(Cursor::new(bytes), &OpenOptions::new().policy(policy)) {
Err(e) => e,
Ok(_) => panic!("the image was expected to be refused and was not"),
}
}
fn root_entries(bytes: &[u8]) -> Result<Vec<Entry>, ReadError> {
let mut r = reader(bytes);
let root = r.root();
r.read_dir(&root)
}
fn root_entries_lenient(bytes: &[u8]) -> Vec<Entry> {
let mut r = lenient(bytes);
let root = r.root();
r.read_dir(&root).expect("a lenient read carries on")
}
fn paths(bytes: &[u8]) -> Vec<Vec<u8>> {
reader(bytes)
.walk()
.expect("walk")
.into_iter()
.map(|e| e.path)
.collect()
}
fn cluster_at(bytes: &[u8], n: u32) -> usize {
reader(bytes)
.layout()
.cluster_start_byte(n)
.expect("a cluster the volume has") as usize
}
fn set_at(bytes: &[u8], dir_cluster: u32, name: &str) -> usize {
let want: Vec<u16> = name.encode_utf16().collect();
let at = cluster_at(bytes, dir_cluster);
let cluster = reader(bytes).layout().bytes_per_cluster as usize;
let mut slot = 0;
while (slot + 1) * DIR_ENTRY_SIZE <= cluster {
let start = at + slot * DIR_ENTRY_SIZE;
let entry = &bytes[start..start + DIR_ENTRY_SIZE];
if EntryType(entry[0]) == EntryType::FILE {
let secondary = usize::from(entry[1]);
let stream = &bytes[start + DIR_ENTRY_SIZE..start + 2 * DIR_ENTRY_SIZE];
let length = usize::from(stream[3]);
let mut units = Vec::new();
for n in 2..=secondary {
let e = &bytes[start + n * DIR_ENTRY_SIZE..start + (n + 1) * DIR_ENTRY_SIZE];
if EntryType(e[0]) != EntryType::FILE_NAME {
continue;
}
for pair in e[2..].as_chunks::<2>().0 {
units.push(u16::from_le_bytes(*pair));
}
}
units.truncate(length);
if units == want {
return start;
}
slot += secondary + 1;
continue;
}
slot += 1;
}
panic!("no entry set names {name} in cluster {dir_cluster}");
}
fn refresh_set_checksum(bytes: &mut [u8], at: usize) {
let slots = usize::from(bytes[at + 1]) + 1;
let checksum = entry_set_checksum(&bytes[at..at + slots * DIR_ENTRY_SIZE]);
bytes[at + 2..at + 4].copy_from_slice(&checksum.to_le_bytes());
}
fn refresh_boot_checksum(bytes: &mut [u8], sector: u64) {
let size = 1usize << bytes[108];
let at = sector as usize * size;
let covered = boot_checksum(&bytes[at..at + 11 * size]);
write_checksum_sector(&mut bytes[at + 11 * size..at + 12 * size], covered);
}
fn scan_of(bytes: &[u8]) -> Vec<Finding> {
lenient(bytes).scan().to_report().findings().to_vec()
}
#[test]
fn a_tree_written_by_this_crate_reads_back_whole() {
let bytes = image();
assert_eq!(
paths(&bytes),
vec![
b"/BIG.BIN".to_vec(),
b"/DCIM".to_vec(),
b"/DCIM/A name long enough to need two entries.txt".to_vec(),
b"/DCIM/EMPTY.BIN".to_vec(),
b"/DCIM/READY.TXT".to_vec(),
]
);
let mut r = reader(&bytes);
for (path, contents) in [
(&b"/DCIM/READY.TXT"[..], &b"hello\n"[..]),
(b"/DCIM/EMPTY.BIN", b""),
(b"/DCIM/A name long enough to need two entries.txt", b"two"),
] {
let node = r.lookup(path).expect("look the path up");
assert_eq!(r.read_data(&node).expect("read"), contents, "{path:?}");
}
let big = r.lookup(b"/BIG.BIN").expect("look /BIG.BIN up");
assert_eq!(r.read_data(&big).expect("read"), vec![0x5a; 9_000]);
assert!(r.scan().is_clean(), "{}", r.scan().to_report().to_table());
}
#[test]
fn a_layout_read_back_is_the_layout_that_was_planned() {
let image = format(tree(), VOLUME, FormatOptions::new(0x1234_5678)).expect("format");
let planned = *image.layout();
let bytes = image.into_bytes();
assert_eq!(reader(&bytes).layout(), &planned);
}
#[test]
fn the_times_an_entry_records_come_back_as_the_instants_that_went_in() {
let bytes = image();
let mut r = reader(&bytes);
let node = r.lookup(b"/DCIM/READY.TXT").expect("look up");
let times = node.times.expect("a file has times");
assert_eq!(times.modify, TIME);
assert_eq!(times.access, TIME);
assert_eq!(times.modify_offset, Some(0));
assert_eq!(times.access_offset, Some(0));
assert_eq!(times.create_offset, Some(0));
assert_eq!(r.root().times, None);
}
#[test]
fn a_zone_offset_moves_the_instant_and_an_absent_one_reads_as_utc() {
let mut file = FileEntry::read_from(&{
let mut buf = [0u8; DIR_ENTRY_SIZE];
buf[0] = EntryType::FILE.0;
buf
})
.expect("a file entry");
let stamp = DosTimestamp::encode(TIME).expect("in range");
file.create = super::super::ondisk::pack_timestamp(stamp);
file.modify = file.create;
file.access = file.create;
file.create_tenth = stamp.tenth;
file.modify_tenth = stamp.tenth;
file.create_utc_offset = UTC_OFFSET;
file.modify_utc_offset = UTC_OFFSET;
file.access_utc_offset = UTC_OFFSET;
assert_eq!(times_of(&file).modify, TIME);
file.modify_utc_offset = UTC_OFFSET_VALID | 0x04;
let east = times_of(&file);
assert_eq!(east.modify.secs, TIME.secs - 3600);
assert_eq!(east.modify_offset, Some(60));
file.modify_utc_offset = 0;
let bare = times_of(&file);
assert_eq!(bare.modify, TIME);
assert_eq!(bare.modify_offset, None);
}
#[test]
fn a_volume_answers_to_the_name_its_root_directory_records() {
let labelled = format(
TreeBuilder::new(),
VOLUME,
FormatOptions::new(1).label(VolumeLabel::new("CARD").expect("a label")),
)
.expect("format")
.into_bytes();
assert_eq!(reader(&labelled).volume_label(), Some(&b"CARD"[..]));
let unnamed = image_of(TreeBuilder::new());
assert_eq!(reader(&unnamed).volume_label(), None);
}
#[test]
fn a_label_field_the_reader_cannot_read_as_a_name_is_named_rather_than_invented() {
let mut bytes = image_of(TreeBuilder::new());
let root = cluster_at(&bytes, reader(&bytes).layout().first_cluster_of_root);
assert_eq!(bytes[root], EntryType::VOLUME_LABEL.0, "the first slot");
bytes[root + 1] = 200;
let err = open_err(&bytes, ReadPolicy::Strict);
assert!(
matches!(
err,
ReadError::LabelTooLong {
count: 200,
limit: MAX_LABEL_UNITS
}
),
"{err}"
);
let mut r = lenient(&bytes);
assert_eq!(r.volume_label(), None);
let details: Vec<_> = r
.scan()
.to_report()
.findings()
.iter()
.map(|f| f.detail.clone())
.collect();
assert!(
details.iter().any(|d| d.contains("carries a NUL")),
"{details:#?}"
);
}
#[test]
fn a_second_entry_of_a_kind_the_root_owns_one_of_is_named() {
let bytes = image_of(TreeBuilder::new());
let root_cluster = reader(&bytes).layout().first_cluster_of_root;
let root = cluster_at(&bytes, root_cluster);
for (entry_type, named) in [
(EntryType::VOLUME_LABEL, "volume label"),
(EntryType::ALLOCATION_BITMAP, "allocation bitmap"),
(EntryType::UPCASE_TABLE, "up-case table"),
] {
let mut bytes = bytes.clone();
let slots = reader(&bytes).layout().bytes_per_cluster as usize / DIR_ENTRY_SIZE;
let source = (0..slots)
.map(|n| root + n * DIR_ENTRY_SIZE)
.find(|at| bytes[*at] == entry_type.0)
.expect("the entry the format writes");
let free = (0..slots)
.map(|n| root + n * DIR_ENTRY_SIZE)
.find(|at| bytes[*at] == 0)
.expect("a slot past the end marker");
let copy: Vec<u8> = bytes[source..source + DIR_ENTRY_SIZE].to_vec();
bytes[free..free + DIR_ENTRY_SIZE].copy_from_slice(©);
let err = open_err(&bytes, ReadPolicy::Strict);
assert!(
matches!(err, ReadError::DuplicateRootEntry { entry_type: e, .. } if e == named),
"{named}: {err}"
);
}
}
#[test]
fn a_subdirectory_naming_the_roots_first_cluster_is_not_the_root() {
let mut bytes = image();
let root_cluster = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root_cluster, "DCIM");
let stream = stream_at(set);
bytes[stream + 1] &= !SECONDARY_NO_FAT_CHAIN;
bytes[stream + 20..stream + 24].copy_from_slice(&root_cluster.to_le_bytes());
refresh_set_checksum(&mut bytes, set);
let mut r = lenient(&bytes);
let node = r.lookup(b"/DCIM").expect("look up");
assert_eq!(node.storage, Storage::Chain(root_cluster));
let err = {
let mut strict = reader(&bytes);
let node = strict.lookup(b"/DCIM").expect("look up");
strict
.read_dir(&node)
.expect_err("the root's own entries are misplaced in it")
};
assert!(matches!(err, ReadError::MisplacedRootEntry { .. }), "{err}");
}
#[test]
fn a_lookup_finds_a_name_through_the_folding_the_volume_carries() {
let bytes = image();
let mut r = reader(&bytes);
assert!(r.lookup(b"/dcim/ready.txt").is_ok());
assert!(r.lookup(b"/DCIM/Ready.Txt").is_ok());
assert!(matches!(
r.lookup(b"/DCIM/READY_TXT"),
Err(ReadError::NotFound { .. })
));
assert!(matches!(
r.lookup(b"/DCIM/READY.TXT/nothing"),
Err(ReadError::NotADirectory { .. })
));
}
#[test]
fn an_ascent_lands_where_the_volumes_own_folding_resolves_from() {
let bytes = image();
let mut r = reader(&bytes);
let want = r.lookup(b"/dcim/ready.txt").expect("lookup");
assert_eq!(
r.lookup(b"/DCIM/../dcim/Ready.TXT")
.map(|node| node.storage),
Ok(want.storage)
);
assert_eq!(
r.lookup(b"/dcim/..").map(|n| n.storage),
Ok(r.root().storage)
);
assert!(matches!(
r.lookup(b"/dcim/../DCIM/READY_TXT"),
Err(ReadError::NotFound { .. })
));
}
#[test]
fn the_folding_is_the_volumes_own_and_not_this_crates_copy_of_one() {
let mut bytes = image_of(TreeBuilder::new().file(b"/README".to_vec(), b"x", meta(0o644)));
let (table_at, table_bytes, entry_at) = {
let r = reader(&bytes);
let layout = r.layout();
let table_at = layout
.cluster_start_byte(layout.upcase_cluster)
.expect("a cluster") as usize;
let root_at = layout
.cluster_start_byte(layout.first_cluster_of_root)
.expect("a cluster") as usize;
let entry_at = (0..16)
.map(|n| root_at + n * DIR_ENTRY_SIZE)
.find(|at| bytes[*at] == EntryType::UPCASE_TABLE.0)
.expect("the up-case table's entry");
(table_at, layout.upcase_bytes as usize, entry_at)
};
let identity = [super::super::ondisk::UPCASE_IDENTITY_RUN, 0u16];
let mut table = vec![0u8; 4];
write_upcase_table(&identity, &mut table).expect("write the table");
bytes[table_at..table_at + table_bytes].fill(0);
bytes[table_at..table_at + table.len()].copy_from_slice(&table);
let checksum = upcase_checksum(&bytes[table_at..table_at + table.len()]);
bytes[entry_at + 4..entry_at + 8].copy_from_slice(&checksum.to_le_bytes());
bytes[entry_at + 24..entry_at + 32].copy_from_slice(&(table.len() as u64).to_le_bytes());
let mut r = reader(&bytes);
assert_eq!(r.upcase().folded_units(), 0, "the volume folds nothing");
assert!(r.lookup(b"/README").is_ok());
assert!(
matches!(r.lookup(b"/readme"), Err(ReadError::NotFound { .. })),
"a volume folding nothing resolves names case-sensitively",
);
assert_eq!(
UpcaseTable::recommended().fold(&"readme".encode_utf16().collect::<Vec<_>>()),
UpcaseTable::recommended().fold(&"README".encode_utf16().collect::<Vec<_>>()),
);
}
#[test]
fn a_stream_chained_through_the_table_reads_the_same_as_a_consecutive_one() {
let mut bytes =
image_of(TreeBuilder::new().file(b"/BIG.BIN".to_vec(), vec![0x5a; 9_000], meta(0o644)));
let (root, bytes_per_cluster, fat_at) = {
let r = reader(&bytes);
(
r.layout().first_cluster_of_root,
r.layout().bytes_per_cluster,
r.layout().fat_offset as usize * r.layout().bytes_per_sector as usize,
)
};
let set = set_at(&bytes, root, "BIG.BIN");
let stream = set + DIR_ENTRY_SIZE;
let first = u32::from_le_bytes(bytes[stream + 20..stream + 24].try_into().unwrap());
let clusters = 9_000u32.div_ceil(bytes_per_cluster);
assert!(clusters > 1, "the file must span more than one cluster");
bytes[stream + 1] &= !SECONDARY_NO_FAT_CHAIN;
refresh_set_checksum(&mut bytes, set);
for n in 0..clusters {
let entry = fat_at + (first + n) as usize * 4;
let next = if n + 1 == clusters {
super::super::ondisk::END_OF_CHAIN
} else {
first + n + 1
};
bytes[entry..entry + 4].copy_from_slice(&next.to_le_bytes());
}
let mut r = reader(&bytes);
let node = r.lookup(b"/BIG.BIN").expect("look up");
assert_eq!(node.storage, Storage::Chain(first));
assert_eq!(r.read_data(&node).expect("read"), vec![0x5a; 9_000]);
assert!(r.scan().is_clean(), "{}", r.scan().to_report().to_table());
}
#[test]
fn a_chain_looping_onto_itself_is_told_apart_from_a_cluster_two_streams_share() {
let mut bytes =
image_of(TreeBuilder::new().file(b"/BIG.BIN".to_vec(), vec![0x5a; 9_000], meta(0o644)));
let (root, bytes_per_cluster, fat_at) = {
let r = reader(&bytes);
(
r.layout().first_cluster_of_root,
r.layout().bytes_per_cluster,
r.layout().fat_offset as usize * r.layout().bytes_per_sector as usize,
)
};
let set = set_at(&bytes, root, "BIG.BIN");
let stream = set + DIR_ENTRY_SIZE;
let first = u32::from_le_bytes(bytes[stream + 20..stream + 24].try_into().unwrap());
assert_eq!(9_000u32.div_ceil(bytes_per_cluster), 3);
bytes[stream + 1] &= !SECONDARY_NO_FAT_CHAIN;
refresh_set_checksum(&mut bytes, set);
for (cluster, next) in [(first, first + 1), (first + 1, first)] {
let entry = fat_at + cluster as usize * 4;
bytes[entry..entry + 4].copy_from_slice(&next.to_le_bytes());
}
let mut r = reader(&bytes);
let report = r.scan();
let said = report
.anomalies()
.iter()
.find(|a| a.detail.contains("loops"))
.unwrap_or_else(|| panic!("no loop finding: {}", report.to_report().to_table()))
.detail
.clone();
assert!(
said.contains(&format!(
"the chain from cluster {first} returns to cluster {first}"
)),
"{said}"
);
assert!(
said.contains("BIG.BIN"),
"the owning path rides along: {said}"
);
assert!(
!report
.anomalies()
.iter()
.any(|a| a.detail.contains("more than one stream")),
"a loop is not a cross-link: {}",
report.to_report().to_table()
);
}
#[test]
fn a_consecutive_run_is_read_without_consulting_the_table() {
let mut bytes =
image_of(TreeBuilder::new().file(b"/BIG.BIN".to_vec(), vec![0x5a; 9_000], meta(0o644)));
let (root, fat_at, count) = {
let r = reader(&bytes);
(
r.layout().first_cluster_of_root,
r.layout().fat_offset as usize * r.layout().bytes_per_sector as usize,
r.layout().cluster_count,
)
};
let stream = set_at(&bytes, root, "BIG.BIN") + DIR_ENTRY_SIZE;
let first = u32::from_le_bytes(bytes[stream + 20..stream + 24].try_into().unwrap());
assert_ne!(bytes[stream + 1] & SECONDARY_NO_FAT_CHAIN, 0);
for n in 0..4u32 {
let entry = fat_at + (first + n) as usize * 4;
bytes[entry..entry + 4].copy_from_slice(&(count - 1).to_le_bytes());
}
let mut r = reader(&bytes);
let node = r.lookup(b"/BIG.BIN").expect("look up");
assert_eq!(node.storage, Storage::Contiguous(first));
assert_eq!(r.read_data(&node).expect("read"), vec![0x5a; 9_000]);
}
#[test]
fn a_written_length_behind_a_declared_one_reads_as_zeros_and_stops_no_strict_read() {
let mut bytes =
image_of(TreeBuilder::new().file(b"/F.BIN".to_vec(), vec![0x5a; 300], meta(0o644)));
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "F.BIN");
let stream = set + DIR_ENTRY_SIZE;
bytes[stream + 8..stream + 16].copy_from_slice(&100u64.to_le_bytes());
refresh_set_checksum(&mut bytes, set);
let mut r = reader(&bytes);
let node = r.lookup(b"/F.BIN").expect("a strict read accepts it");
assert_eq!(node.data_length, 300);
assert_eq!(node.valid_data_length, 100);
let read = r.read_data(&node).expect("read");
assert_eq!(read.len(), 300);
assert_eq!(&read[..100], &[0x5a; 100]);
assert!(
read[100..].iter().all(|b| *b == 0),
"the tail reads as zeros"
);
let found = scan_of(&bytes)
.into_iter()
.find(|f| f.detail.contains("of them written"))
.expect("the discrepancy is reported");
assert_eq!(found.severity, Severity::Cosmetic);
}
#[test]
fn a_written_length_past_a_declared_one_is_a_contradiction_and_is_refused() {
let mut bytes =
image_of(TreeBuilder::new().file(b"/F.BIN".to_vec(), vec![0x5a; 300], meta(0o644)));
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "F.BIN");
let stream = set + DIR_ENTRY_SIZE;
bytes[stream + 8..stream + 16].copy_from_slice(&4000u64.to_le_bytes());
refresh_set_checksum(&mut bytes, set);
let err = root_entries(&bytes).expect_err("a strict read refuses it");
assert!(matches!(err, ReadError::ValidLengthPastEnd { .. }), "{err}");
let mut r = lenient(&bytes);
let node = r.lookup(b"/F.BIN").expect("look up");
assert_eq!(node.valid_data_length, 300);
assert_eq!(r.read_data(&node).expect("read").len(), 300);
}
fn stream_at(set: usize) -> usize {
set + DIR_ENTRY_SIZE
}
fn patch_u64(bytes: &mut [u8], set: usize, at: usize, value: u64) {
bytes[at..at + 8].copy_from_slice(&value.to_le_bytes());
refresh_set_checksum(bytes, set);
}
#[test]
fn a_stream_longer_than_the_whole_heap_is_refused_and_its_length_is_held_to_it() {
let mut bytes =
image_of(TreeBuilder::new().file(b"/F.BIN".to_vec(), vec![0x5a; 300], meta(0o644)));
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "F.BIN");
let stream = stream_at(set);
patch_u64(&mut bytes, set, stream + 8, 0);
patch_u64(&mut bytes, set, stream + 24, 8 << 30);
let err = root_entries(&bytes).expect_err("a strict read refuses it");
assert!(matches!(err, ReadError::StreamPastHeap { .. }), "{err}");
let heap = reader(&bytes).layout().heap_bytes();
assert!(heap < 8 << 30, "the fixture is not evidence otherwise");
let mut r = lenient(&bytes);
let node = r.lookup(b"/F.BIN").expect("look up");
assert_eq!(node.data_length, heap);
assert_eq!(
r.read_data_to(&node, std::io::sink()).expect("stream"),
heap
);
}
#[test]
fn a_streamed_read_stops_at_the_cap_a_caller_set() {
let bytes = image();
let mut r = Reader::open_with(
Cursor::new(&bytes[..]),
&OpenOptions::new().limits(Limits::new().max_file_bytes(1024)),
)
.expect("open");
let node = r.lookup(b"/BIG.BIN").expect("look up");
assert!(matches!(
r.read_data_to(&node, std::io::sink()),
Err(ReadError::FileTooLarge { size: 9_000, .. })
));
}
#[test]
fn a_directory_is_read_to_its_end_marker_and_not_to_its_declared_length() {
let mut bytes = image();
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "DCIM");
let stream = stream_at(set);
let heap = reader(&bytes).layout().heap_bytes();
let dcim = reader(&bytes).lookup(b"/DCIM").expect("look up").storage;
let first = dcim.first_cluster().expect("a directory has an allocation");
let bytes_per_cluster = u64::from(reader(&bytes).layout().bytes_per_cluster);
let rest = heap - u64::from(first - FIRST_CLUSTER) * bytes_per_cluster;
bytes[stream + 1] |= SECONDARY_NO_FAT_CHAIN;
patch_u64(&mut bytes, set, stream + 8, rest);
patch_u64(&mut bytes, set, stream + 24, rest);
assert!(rest <= heap && rest <= MAX_DIRECTORY_BYTES);
assert!(
rest / bytes_per_cluster > 1000,
"the fixture declares {} clusters, which is not evidence of anything",
rest / bytes_per_cluster
);
assert_eq!(
reader(&bytes)
.lookup(b"/DCIM")
.expect("look up")
.data_length,
rest
);
let unknown = |bytes: &mut Vec<u8>, at: usize| bytes[at] = 0x9F;
let last = FIRST_CLUSTER + reader(&bytes).layout().cluster_count - 1;
let dcim_at = cluster_at(&bytes, first);
let slots = usize::try_from(bytes_per_cluster).expect("a cluster") / DIR_ENTRY_SIZE;
let marker = dcim_at
+ (0..slots)
.find(|n| bytes[dcim_at + n * DIR_ENTRY_SIZE] == 0)
.expect("the end marker")
* DIR_ENTRY_SIZE;
let mut control = bytes.clone();
unknown(&mut control, marker + DIR_ENTRY_SIZE);
let err = root_entries(&control)
.map(|_| ())
.and_then(|()| {
let mut r = reader(&control);
let node = r.lookup(b"/DCIM")?;
r.read_dir(&node).map(|_| ())
})
.expect_err("the probe is met in the cluster the marker sits in");
assert!(matches!(err, ReadError::EntriesAfterEnd { .. }), "{err}");
let last_at = cluster_at(&bytes, last);
unknown(&mut bytes, last_at);
let mut r = reader(&bytes);
let node = r.lookup(b"/DCIM").expect("look up");
let entries = r
.read_dir(&node)
.expect("the read stopped at the marker, so the probe was never met");
assert_eq!(entries.len(), 3, "and it is still the directory it was");
}
#[test]
fn a_directory_longer_than_the_format_allows_one_is_refused() {
let bytes = image();
let mut r = reader(&bytes);
r.layout.cluster_count = 100_000;
assert!(r.layout.heap_bytes() > MAX_DIRECTORY_BYTES);
let mut strict = OnDeviation::Policy(ReadPolicy::Strict);
let err = r
.bound_length(MAX_DIRECTORY_BYTES + 1, true, 7, &mut strict)
.expect_err("a strict read refuses it");
assert!(
matches!(err, ReadError::DirectoryTooLong { index: 7, .. }),
"{err}"
);
let mut lenient = OnDeviation::Policy(ReadPolicy::Lenient);
assert_eq!(
r.bound_length(MAX_DIRECTORY_BYTES + 1, true, 7, &mut lenient)
.expect("a lenient read carries on"),
MAX_DIRECTORY_BYTES
);
assert_eq!(
r.bound_length(MAX_DIRECTORY_BYTES + 1, false, 7, &mut lenient)
.expect("a lenient read carries on"),
MAX_DIRECTORY_BYTES + 1
);
}
fn a_volume_with_one_file() -> (Vec<u8>, usize, usize) {
let bytes =
image_of(TreeBuilder::new().file(b"/F.BIN".to_vec(), vec![0x5a; 300], meta(0o644)));
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "F.BIN");
let stream = stream_at(set);
(bytes, set, stream)
}
#[test]
fn a_stream_recording_a_length_and_no_first_cluster_is_named_where_it_is_read() {
let (mut bytes, set, stream) = a_volume_with_one_file();
bytes[stream + 20..stream + 24].copy_from_slice(&0u32.to_le_bytes());
patch_u64(&mut bytes, set, stream + 8, 9_000);
patch_u64(&mut bytes, set, stream + 24, 9_000);
let err = root_entries(&bytes).expect_err("a strict read refuses it");
assert!(
matches!(
err,
ReadError::StreamWithoutAllocation {
declared: 9_000,
..
}
),
"{err}"
);
assert_eq!(err.anomaly().severity, Severity::Structural);
}
#[test]
fn a_stream_recording_a_first_cluster_and_no_length_is_named_where_it_is_read() {
let (mut bytes, set, stream) = a_volume_with_one_file();
patch_u64(&mut bytes, set, stream + 8, 0);
patch_u64(&mut bytes, set, stream + 24, 0);
let err = root_entries(&bytes).expect_err("a strict read refuses it");
assert!(
matches!(err, ReadError::AllocationWithoutLength { .. }),
"{err}"
);
assert_eq!(err.anomaly().severity, Severity::Conformance);
}
#[test]
fn a_directory_whose_length_is_not_whole_clusters_is_named() {
let mut bytes = image();
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "DCIM");
patch_u64(&mut bytes, set, stream_at(set) + 24, 1);
let err = root_entries(&bytes).expect_err("a strict read refuses it");
assert!(
matches!(
err,
ReadError::DirectoryLengthNotClusters { declared: 1, .. }
),
"{err}"
);
}
#[test]
fn attribute_bits_the_format_reserves_are_named() {
let mut bytes = image();
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "DCIM");
let attributes = u16::from_le_bytes([bytes[set + 4], bytes[set + 5]]) | 0xF008;
bytes[set + 4..set + 6].copy_from_slice(&attributes.to_le_bytes());
refresh_set_checksum(&mut bytes, set);
let err = root_entries(&bytes).expect_err("a strict read refuses it");
assert!(
matches!(err, ReadError::ReservedAttributes { bits: 0xF008, .. }),
"{err}"
);
assert_eq!(FileAttributes::DEFINED.bits(), 0x0037);
}
#[test]
fn a_stream_with_an_allocation_and_no_allocation_declared_possible_is_named() {
let mut bytes = image();
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "DCIM");
let stream = stream_at(set);
assert_ne!(
bytes[stream + 1] & SECONDARY_ALLOCATION_POSSIBLE,
0,
"the writer sets it, which is what makes clearing it the case under test"
);
bytes[stream + 1] &= !SECONDARY_ALLOCATION_POSSIBLE;
refresh_set_checksum(&mut bytes, set);
let err = root_entries(&bytes).expect_err("a strict read refuses it");
assert!(
matches!(err, ReadError::AllocationNotPossible { .. }),
"{err}"
);
}
#[test]
fn a_time_the_encoding_does_not_define_is_named_where_the_entry_is_read() {
for (offset, field) in [(8usize, "creation time"), (16, "access time")] {
let mut bytes = image();
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "DCIM");
bytes[set + offset..set + offset + 4].copy_from_slice(&0u32.to_le_bytes());
refresh_set_checksum(&mut bytes, set);
let err = root_entries(&bytes).expect_err("a strict read refuses it");
assert!(
matches!(err, ReadError::MalformedTimestamp { field: f, .. } if f == field),
"{field}: {err}"
);
}
let mut bytes = image();
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "DCIM");
bytes[set + 20] = 255;
refresh_set_checksum(&mut bytes, set);
let err = root_entries(&bytes).expect_err("a strict read refuses it");
assert!(
matches!(
err,
ReadError::MalformedTimestamp {
field: "creation time",
..
}
),
"{err}"
);
}
#[test]
fn a_set_carrying_a_name_entry_its_name_does_not_reach_is_named() {
let mut bytes = image();
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "DCIM");
assert_eq!(bytes[set + 1], 2, "a file entry, a stream and one name");
bytes[set + 1] = 3;
let third = set + 3 * DIR_ENTRY_SIZE;
let mut extra = [0u8; DIR_ENTRY_SIZE];
FileNameEntry::new(&[0x0041])
.write_to(&mut extra)
.expect("write");
bytes[third..third + DIR_ENTRY_SIZE].copy_from_slice(&extra);
refresh_set_checksum(&mut bytes, set);
let err = root_entries(&bytes).expect_err("a strict read refuses it");
assert!(
matches!(
err,
ReadError::ExcessNameEntries {
want: 1,
have: 2,
..
}
),
"{err}"
);
assert!(
root_entries_lenient(&bytes)
.iter()
.any(|e| e.name == b"DCIM")
);
}
#[test]
fn a_volume_recording_two_allocation_tables_is_refused_by_name_under_either_policy() {
let mut bytes = image();
bytes[110] = 2;
refresh_boot_checksum(&mut bytes, 0);
for policy in [ReadPolicy::Strict, ReadPolicy::Lenient] {
let err = open_err(&bytes, policy);
assert!(matches!(err, ReadError::TexFat), "{policy:?}: {err}");
}
for count in [0u8, 3, 255] {
let mut bytes = image();
bytes[110] = count;
refresh_boot_checksum(&mut bytes, 0);
let err = open_err(&bytes, ReadPolicy::Strict);
assert!(matches!(err, ReadError::FatCount { .. }), "{count}: {err}");
}
}
#[test]
fn a_volume_whose_root_names_no_bitmap_or_no_table_is_refused_rather_than_read_empty() {
for entry_type in [EntryType::ALLOCATION_BITMAP, EntryType::UPCASE_TABLE] {
let mut bytes = image();
let root = reader(&bytes).layout().first_cluster_of_root;
let at = cluster_at(&bytes, root);
let slot = (0..8)
.map(|n| at + n * DIR_ENTRY_SIZE)
.find(|at| bytes[*at] == entry_type.0)
.expect("the describing entry");
bytes[slot] = entry_type.cleared().0;
for policy in [ReadPolicy::Strict, ReadPolicy::Lenient] {
let err = open_err(&bytes, policy);
assert!(
matches!(err, ReadError::MissingResident { .. }),
"{entry_type:?} under {policy:?}: {err}"
);
}
}
}
#[test]
fn a_slot_whose_in_use_bit_is_clear_is_stepped_over_rather_than_read_as_the_end() {
let bytes = image();
let root = reader(&bytes).layout().first_cluster_of_root;
let at = cluster_at(&bytes, root);
let guid = at + DIR_ENTRY_SIZE;
assert_eq!(bytes[guid], EntryType::VOLUME_GUID.cleared().0);
assert!(!EntryType(bytes[guid]).is_end_of_directory());
assert!(!paths(&bytes).is_empty());
}
#[test]
fn a_damaged_boot_region_checksum_is_named_and_the_main_region_is_still_preferred() {
let mut bytes = image();
bytes[64] ^= 0x01; let err = open_err(&bytes, ReadPolicy::Strict);
assert!(
matches!(err, ReadError::BootChecksumMismatch { sector: 0, .. }),
"{err}"
);
let anomaly = err.anomaly();
assert_eq!(anomaly.severity, Severity::Integrity);
assert_eq!(anomaly.category, Category::BootRegion);
let r = lenient(&bytes);
assert_eq!(r.boot_sector().partition_offset, bytes_u64(&bytes, 64));
}
#[test]
fn a_backup_region_describing_a_different_volume_is_named() {
let mut bytes = image();
let sector = reader(&bytes).layout().bytes_per_sector as usize;
let backup = 12 * sector;
bytes[backup + 100..backup + 104].copy_from_slice(&0xdead_beefu32.to_le_bytes());
refresh_boot_checksum(&mut bytes, 12);
let err = open_err(&bytes, ReadPolicy::Strict);
assert!(
matches!(err, ReadError::BackupBootRegionDiffers { .. }),
"{err}"
);
assert!(err.to_string().contains("VolumeSerialNumber"), "{err}");
assert_eq!(err.anomaly().severity, Severity::Conformance);
}
#[test]
fn the_two_fields_a_driver_rewrites_are_not_held_against_the_backup() {
let mut bytes = image();
bytes[106] = 0x02; bytes[112] = 99; let r = lenient(&bytes);
assert!(r.volume_dirty());
let report = r.boot_sector().volume_flags;
assert_eq!(report & 0x0002, 0x0002);
assert!(
!scan_of(&bytes)
.iter()
.any(|a| a.detail.contains("does not describe the same volume")),
"a driver's own two fields are not a backup that has drifted",
);
}
#[test]
fn a_volume_a_driver_left_open_is_a_remark_and_not_a_refusal() {
let mut bytes = image();
bytes[106] = 0x02;
let mut r = Reader::open(Cursor::new(&bytes)).expect("a strict read accepts it");
assert!(r.volume_dirty());
assert!(!r.media_failure());
assert!(!r.scan().has_fatal(ReadPolicy::Strict));
let found = scan_of(&bytes)
.into_iter()
.find(|f| f.detail.contains("not cleanly unmounted"))
.expect("the state is reported");
assert_eq!(found.severity, Severity::Cosmetic);
assert!(!found.detail.contains("VolumeFlags"), "{}", found.detail);
let mut bytes = image();
bytes[106] = 0x04;
let r = Reader::open(Cursor::new(&bytes)).expect("a strict read accepts it");
assert!(r.media_failure());
}
#[test]
fn a_major_revision_this_reader_does_not_implement_is_refused_and_a_minor_one_is_a_remark() {
for revision in [0x0200u16, 0xFFFF] {
let mut bytes = image();
for region in [0u64, BOOT_REGION_SECTORS] {
let at = region as usize * 512;
bytes[at + 104..at + 106].copy_from_slice(&revision.to_le_bytes());
refresh_boot_checksum(&mut bytes, region);
}
for policy in [ReadPolicy::Strict, ReadPolicy::Lenient] {
let err = open_err(&bytes, policy);
assert!(
matches!(err, ReadError::BadBootSector { .. }),
"{revision:#06x} under {policy:?}: {err}"
);
assert!(err.to_string().contains("revision"), "{err}");
}
assert!(
crate::detect(Cursor::new(&bytes)).is_err(),
"{revision:#06x}"
);
}
let mut bytes = image();
for region in [0u64, BOOT_REGION_SECTORS] {
let at = region as usize * 512;
bytes[at + 104..at + 106].copy_from_slice(&0x0103u16.to_le_bytes());
refresh_boot_checksum(&mut bytes, region);
}
let err = open_err(&bytes, ReadPolicy::Strict);
assert!(
matches!(err, ReadError::UnknownMinorRevision { minor: 3 }),
"{err}"
);
let found = scan_of(&bytes)
.into_iter()
.find(|f| f.detail.contains("minor revision"))
.expect("the revision is reported");
assert_eq!(found.severity, Severity::Conformance);
}
#[test]
fn an_extended_boot_sector_missing_its_signature_is_named() {
for region in [0u64, BOOT_REGION_SECTORS] {
let mut bytes = image();
let at = (region as usize + 1) * 512;
bytes[at + 508..at + 512].copy_from_slice(&0u32.to_le_bytes());
refresh_boot_checksum(&mut bytes, region);
let err = open_err(&bytes, ReadPolicy::Strict);
assert!(
matches!(
err,
ReadError::BadExtendedBootSignature {
sector,
found: 0,
expected: EXTENDED_BOOT_SIGNATURE,
} if sector == region + 1
),
"region {region}: {err}"
);
}
let mut bytes = image();
for sector in 1..=EXTENDED_BOOT_SECTORS as usize {
let at = sector * 512;
bytes[at + 508..at + 512].copy_from_slice(&0u32.to_le_bytes());
}
refresh_boot_checksum(&mut bytes, 0);
let named: Vec<_> = scan_of(&bytes)
.into_iter()
.filter(|f| f.detail.contains("extended boot sector"))
.collect();
assert_eq!(named.len(), 1, "{named:#?}");
assert_eq!(named[0].severity, Severity::Conformance);
}
#[test]
fn a_chain_reaching_a_cluster_the_table_marks_bad_is_named_as_that() {
let mut bytes =
image_of(TreeBuilder::new().file(b"/F.BIN".to_vec(), vec![0x5a; 9_000], meta(0o644)));
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "F.BIN");
let stream = stream_at(set);
bytes[stream + 1] &= !SECONDARY_NO_FAT_CHAIN;
refresh_set_checksum(&mut bytes, set);
let first = u32::from_le_bytes([
bytes[stream + 20],
bytes[stream + 21],
bytes[stream + 22],
bytes[stream + 23],
]);
let entry = reader(&bytes)
.layout()
.fat_entry_byte(first)
.expect("an entry for the first cluster") as usize;
bytes[entry..entry + 4].copy_from_slice(&BAD_CLUSTER.to_le_bytes());
let mut r = lenient(&bytes);
let node = r.lookup(b"/F.BIN").expect("look up");
let err = r
.read_data(&node)
.expect_err("the chain runs into the mark");
assert!(
matches!(err, ReadError::BadClusterInChain { cluster } if cluster == BAD_CLUSTER),
"{err}"
);
}
#[test]
fn a_percentage_the_field_cannot_hold_is_a_different_remark_from_a_stale_one() {
let mut bytes = image();
bytes[112] = 200;
let found = scan_of(&bytes)
.into_iter()
.find(|f| f.detail.contains("PercentInUse"))
.expect("the value is reported");
assert_eq!(found.severity, Severity::Conformance);
assert!(!found.detail.contains("200%"), "{}", found.detail);
let mut bytes = image();
bytes[112] = 99;
let found = scan_of(&bytes)
.into_iter()
.find(|f| f.detail.contains("99% in use"))
.expect("the staleness is reported");
assert_eq!(found.severity, Severity::Cosmetic);
let mut bytes = image();
bytes[112] = PERCENT_IN_USE_UNKNOWN;
assert!(
!scan_of(&bytes)
.iter()
.any(|f| f.detail.contains("PercentInUse") || f.detail.contains("in use and")),
"the format's own value for an unmeasured volume is not a deviation"
);
}
#[test]
fn an_up_case_table_that_is_not_the_mapping_its_entry_advertises_is_named() {
let mut bytes = image();
let table = cluster_at(&bytes, reader(&bytes).layout().upcase_cluster);
bytes[table + 200] ^= 0xff;
let err = open_err(&bytes, ReadPolicy::Strict);
assert!(
matches!(err, ReadError::UpcaseChecksumMismatch { .. }),
"{err}"
);
assert_eq!(err.anomaly().severity, Severity::Integrity);
assert_eq!(err.anomaly().category, Category::UpcaseTable);
assert!(lenient(&bytes).upcase().folded_units() > 0);
}
#[test]
fn a_damaged_entry_set_checksum_is_named() {
let mut bytes = image();
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "BIG.BIN");
bytes[set + 4] ^= 0x01;
let err = root_entries(&bytes).expect_err("a strict read refuses");
assert!(
matches!(err, ReadError::SetChecksumMismatch { .. }),
"{err}"
);
assert_eq!(err.anomaly().severity, Severity::Integrity);
}
#[test]
fn a_name_hash_no_name_produces_is_named_where_no_checksum_covers_it() {
let mut bytes = image();
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "BIG.BIN");
let stream = set + DIR_ENTRY_SIZE;
let was = u16::from_le_bytes(bytes[stream + 4..stream + 6].try_into().unwrap());
bytes[stream + 4..stream + 6].copy_from_slice(&(was ^ 0x0001).to_le_bytes());
refresh_set_checksum(&mut bytes, set);
let err = root_entries(&bytes).expect_err("a strict read refuses");
assert!(matches!(err, ReadError::NameHashMismatch { .. }), "{err}");
assert_eq!(err.anomaly().severity, Severity::Integrity);
}
#[test]
fn a_name_no_directory_can_hold_is_refused_where_the_reader_resolves_it() {
for name in ["..", ".", "a/b", "a\u{0}b"] {
let mut bytes = image_of(TreeBuilder::new().file(b"/XX".to_vec(), b"x", meta(0o644)));
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "XX");
let stream = set + DIR_ENTRY_SIZE;
let units: Vec<u16> = name.encode_utf16().collect();
bytes[stream + 3] = units.len() as u8;
let hash = name_hash(&UpcaseTable::recommended().fold(&units));
bytes[stream + 4..stream + 6].copy_from_slice(&hash.to_le_bytes());
let name_entry = set + 2 * DIR_ENTRY_SIZE;
bytes[name_entry + 2..name_entry + DIR_ENTRY_SIZE].fill(0);
for (n, unit) in units.iter().enumerate() {
let at = name_entry + 2 + n * 2;
bytes[at..at + 2].copy_from_slice(&unit.to_le_bytes());
}
refresh_set_checksum(&mut bytes, set);
let err = root_entries(&bytes).expect_err("a strict read refuses");
assert!(
matches!(err, ReadError::HostileName { .. }),
"{name:?}: {err}"
);
assert_eq!(err.anomaly().severity, Severity::Structural);
let names = root_entries_lenient(&bytes);
assert!(names.is_empty(), "{name:?}: the name was handed back");
}
}
#[test]
fn an_entry_set_that_ends_before_it_said_it_would_is_named() {
let mut bytes = image_of(TreeBuilder::new().file(b"/XX".to_vec(), b"x", meta(0o644)));
let root = reader(&bytes).layout().first_cluster_of_root;
let set = set_at(&bytes, root, "XX");
bytes[set + 1] += 1;
refresh_set_checksum(&mut bytes, set);
let err = root_entries(&bytes).expect_err("a strict read refuses");
assert!(matches!(err, ReadError::IncompleteEntrySet { .. }), "{err}");
assert_eq!(err.anomaly().severity, Severity::Structural);
}
#[test]
fn an_entry_continuing_a_set_no_entry_opened_is_named() {
let mut bytes = image_of(TreeBuilder::new());
let root = reader(&bytes).layout().first_cluster_of_root;
let at = cluster_at(&bytes, root);
let slot = at + 4 * DIR_ENTRY_SIZE;
bytes[slot] = EntryType::FILE_NAME.0;
let err = root_entries(&bytes).expect_err("a strict read refuses");
assert!(
matches!(err, ReadError::StraySecondaryEntry { .. }),
"{err}"
);
}
#[test]
fn an_entry_of_a_critical_type_this_reader_does_not_know_is_named_and_a_benign_one_is_not() {
let root = {
let bytes = image_of(TreeBuilder::new());
reader(&bytes).layout().first_cluster_of_root
};
let mut bytes = image_of(TreeBuilder::new());
let at = cluster_at(&bytes, root);
bytes[at + 4 * DIR_ENTRY_SIZE] = 0x9F; let err = root_entries(&bytes).expect_err("a strict read refuses");
assert!(
matches!(err, ReadError::UnknownCriticalEntry { .. }),
"{err}"
);
assert_eq!(err.anomaly().severity, Severity::Conformance);
let mut bytes = image_of(TreeBuilder::new());
bytes[at + 4 * DIR_ENTRY_SIZE] = 0xBF; assert!(
root_entries(&bytes).is_ok(),
"a benign entry is carried through rather than refused",
);
}
#[test]
fn an_entry_after_the_end_marker_is_named_once_and_never_handed_back() {
let mut bytes = image_of(TreeBuilder::new().file(b"/XX".to_vec(), b"x", meta(0o644)));
let root = reader(&bytes).layout().first_cluster_of_root;
let at = cluster_at(&bytes, root);
let set = set_at(&bytes, root, "XX");
assert!(set > at);
bytes[set] = 0;
let orphan = set + 4 * DIR_ENTRY_SIZE;
bytes[orphan] = EntryType::VOLUME_GUID.0;
let err = root_entries(&bytes).expect_err("a strict read refuses");
assert!(matches!(err, ReadError::EntriesAfterEnd { .. }), "{err}");
let entries = root_entries_lenient(&bytes);
assert!(entries.is_empty(), "nothing past the marker is a name");
}
#[test]
fn a_cluster_a_stream_occupies_and_the_bitmap_calls_free_is_named() {
let mut bytes =
image_of(TreeBuilder::new().file(b"/F.BIN".to_vec(), vec![0x5a; 300], meta(0o644)));
let (root, bitmap_cluster) = {
let r = reader(&bytes);
(r.layout().first_cluster_of_root, r.layout().bitmap_cluster)
};
let stream = set_at(&bytes, root, "F.BIN") + DIR_ENTRY_SIZE;
let first = u32::from_le_bytes(bytes[stream + 20..stream + 24].try_into().unwrap());
let bit = (first - FIRST_CLUSTER) as usize;
let at = cluster_at(&bytes, bitmap_cluster) + bit / 8;
assert_ne!(bytes[at] & (1 << (bit % 8)), 0, "the bit was set");
bytes[at] &= !(1 << (bit % 8));
let found = scan_of(&bytes);
assert!(
found
.iter()
.any(|a| a.detail.contains("the allocation bitmap says it is free")),
"{found:#?}"
);
let mut r = lenient(&bytes);
let node = r.lookup(b"/F.BIN").expect("look up");
assert_eq!(r.read_data(&node).expect("read").len(), 300);
}
#[test]
fn clusters_the_bitmap_holds_and_nothing_reaches_are_named() {
let mut bytes = image();
let bitmap = cluster_at(&bytes, reader(&bytes).layout().bitmap_cluster);
bytes[bitmap + 40] |= 0b1001;
let found = scan_of(&bytes);
let lost = found
.iter()
.find(|a| a.detail.contains("reached by nothing"))
.expect("the clusters are named");
assert!(lost.detail.contains('2'), "{}", lost.detail);
assert_eq!(lost.severity, Severity::Conformance);
}
#[test]
fn a_reserved_table_entry_the_format_fixes_is_held_to_it() {
let mut bytes = image();
let fat = reader(&bytes).layout().fat_offset as usize
* reader(&bytes).layout().bytes_per_sector as usize;
bytes[fat + 4..fat + 8].copy_from_slice(&0u32.to_le_bytes());
let found = scan_of(&bytes);
assert!(
found.iter().any(|a| a.detail.contains("table entry 1")),
"{found:#?}"
);
}
#[test]
fn a_clean_volume_scans_clean_at_every_cluster_size_the_writer_reaches() {
use crate::exfat::{ClusterSize, PlanRequest};
for (bytes_total, cluster) in [
(32u64 << 20, ClusterSize::Bytes(512)),
(64 << 20, ClusterSize::Auto),
(256 << 20, ClusterSize::Bytes(128 << 10)),
] {
let options = FormatOptions::new(7).plan(PlanRequest::new(0).cluster_size(cluster));
let image = format(tree(), bytes_total, options).expect("format");
let bytes = image.into_bytes();
let mut r = reader(&bytes);
let report = r.scan();
assert!(
report.is_clean(),
"{bytes_total} at {cluster:?}:\n{}",
report.to_report().to_table()
);
assert_eq!(paths(&bytes).len(), 5);
}
}
#[test]
fn a_walk_stops_at_the_cap_a_caller_set() {
let bytes = image();
let mut r = Reader::open_with(
Cursor::new(&bytes[..]),
&OpenOptions::new().limits(Limits::new().max_walk_entries(2)),
)
.expect("open");
assert!(matches!(
r.walk(),
Err(ReadError::WalkTooLarge { limit: 2 })
));
}
#[test]
fn a_whole_file_read_stops_at_the_cap_a_caller_set() {
let bytes = image();
let mut r = Reader::open_with(
Cursor::new(&bytes[..]),
&OpenOptions::new().limits(Limits::new().max_file_bytes(1024)),
)
.expect("open");
let node = r.lookup(b"/BIG.BIN").expect("look up");
assert!(matches!(
r.read_data(&node),
Err(ReadError::FileTooLarge { size: 9_000, .. })
));
let mut buf = [0u8; 16];
assert_eq!(r.read_into(&node, 0, &mut buf).expect("read"), 16);
}
#[test]
fn a_directory_that_points_at_itself_terminates_a_walk() {
let mut bytes = image_of(
TreeBuilder::new()
.directory(b"/a".to_vec(), meta(0o755))
.directory(b"/a/b".to_vec(), meta(0o755)),
);
let root = reader(&bytes).layout().first_cluster_of_root;
let a_cluster = {
let mut r = reader(&bytes);
let node = r.lookup(b"/a").expect("look up");
node.storage.first_cluster().expect("a directory has one")
};
let set = set_at(&bytes, a_cluster, "b");
let stream = set + DIR_ENTRY_SIZE;
bytes[stream + 20..stream + 24].copy_from_slice(&a_cluster.to_le_bytes());
refresh_set_checksum(&mut bytes, set);
assert_ne!(a_cluster, root);
let names = paths(&bytes);
assert_eq!(names, vec![b"/a".to_vec(), b"/a/b".to_vec()]);
}
#[test]
fn a_directory_ending_on_the_heaps_last_cluster_is_read_rather_than_refused() {
let mut bytes = image_of(TreeBuilder::new().directory(b"/d".to_vec(), meta(0o755)));
let (root, last) = {
let r = reader(&bytes);
let layout = r.layout();
(
layout.first_cluster_of_root,
FIRST_CLUSTER + layout.cluster_count - 1,
)
};
let set = set_at(&bytes, root, "d");
let stream = set + DIR_ENTRY_SIZE;
bytes[stream + 20..stream + 24].copy_from_slice(&last.to_le_bytes());
refresh_set_checksum(&mut bytes, set);
let mut r = lenient(&bytes);
let node = r.lookup(b"/d").expect("look the directory up");
assert_eq!(node.storage, Storage::Contiguous(last));
assert!(r.read_dir(&node).expect("read the last cluster").is_empty());
}
#[test]
fn a_directory_whose_chain_repeats_a_cluster_is_refused_rather_than_followed() {
let mut bytes = image();
let (root, fat) = {
let r = reader(&bytes);
(
r.layout().first_cluster_of_root,
r.layout().fat_offset as usize * r.layout().bytes_per_sector as usize,
)
};
let entry = fat + root as usize * 4;
bytes[entry..entry + 4].copy_from_slice(&root.to_le_bytes());
let err = open_err(&bytes, ReadPolicy::Strict);
assert!(matches!(err, ReadError::ChainTooLong { .. }), "{err}");
}
#[test]
fn a_reader_never_panics_on_mangled_images() {
let image = image();
fn drive(bytes: &[u8]) {
if let Ok(mut r) = Reader::open(Cursor::new(bytes)) {
let _ = r.volume_label();
if let Ok(entries) = r.walk() {
for e in &entries {
let _ = r.read_data(&e.node);
}
for e in &entries {
let _ = r.lookup(&e.path);
}
}
}
if let Ok(mut r) = Reader::open_with(
Cursor::new(bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
) {
let report = r.scan();
let _ = report.to_report().to_json();
let _ = report.to_report().to_table();
let _ = r.walk();
}
if let Ok(mut r) = Reader::open_with(
Cursor::new(bytes),
&OpenOptions::new().base(512).policy(ReadPolicy::Lenient),
) {
let _ = r.scan();
}
}
drive(&image);
for (off, len, fill) in [
(72usize, 8usize, 0xffu8), (80, 4, 0xff), (84, 4, 0xff), (88, 4, 0xff), (92, 4, 0xff), (96, 4, 0xff), (108, 1, 0x00), (108, 1, 0xff), (109, 1, 0xff), (110, 1, 0x00), ] {
let mut mangled = image.clone();
mangled[off..off + len].fill(fill);
drive(&mangled);
}
for len in [0usize, 1, 511, 512, 513, 4096, 6144, 65_536, 1 << 20] {
drive(&image[..len.min(image.len())]);
}
let mut flip = image.clone();
let span = flip.len().min(1 << 20);
let mut i = 0usize;
while i < span {
let orig = flip[i];
flip[i] ^= 0xff;
drive(&flip);
flip[i] = orig;
i += 4093; }
drive(&vec![0x00u8; 1 << 16]);
drive(&vec![0xffu8; 1 << 16]);
let ramp: Vec<u8> = (0..1u32 << 16).map(|k| (k % 256) as u8).collect();
drive(&ramp);
}
#[test]
fn the_extraction_surface_answers_for_every_node_a_walk_reaches() {
let bytes = image();
let mut r = reader(&bytes);
let synthesis = Synthesis::new();
let mut seen = Vec::new();
r.walk_tree::<TreeError, _>(|reader, entry| {
let attrs = reader.stat(&entry.node, &synthesis)?;
assert!(attrs.synthesized.contains(&Property::Ownership));
assert!(attrs.synthesized.contains(&Property::Permissions));
assert!(attrs.xattrs.is_empty());
assert_eq!(entry.shared, None);
seen.push((entry.path.clone(), entry.kind));
Ok(())
})
.expect("walk");
assert_eq!(seen[0].0, Vec::<u8>::new(), "the root comes first");
assert_eq!(seen.len(), 6);
assert!(matches!(seen[1].1, NodeKind::File { size: 9_000 }));
let root = r.root();
assert!(matches!(
r.link_target(&root),
Err(TreeError::Malformed { .. })
));
}
#[test]
fn a_read_only_file_comes_back_with_its_write_bits_cleared() {
let bytes = image();
let mut r = reader(&bytes);
let node = r
.lookup(b"/DCIM/A name long enough to need two entries.txt")
.expect("look up");
let attrs = r.stat(&node, &Synthesis::new()).expect("stat");
assert_eq!(attrs.meta.mode & 0o222, 0);
}
#[test]
fn every_read_error_answers_with_an_anomaly_that_says_where_it_was() {
let all = [
ReadError::Io {
kind: std::io::ErrorKind::UnexpectedEof,
message: "x".to_string(),
},
ReadError::Parse(ParseError::TooShort {
structure: "x",
need: 1,
got: 0,
}),
ReadError::BadBootSector {
detail: "x".to_string(),
},
ReadError::TexFat,
ReadError::FatCount { count: 3 },
ReadError::BootChecksumMismatch {
sector: 0,
computed: 1,
stored: 2,
},
ReadError::BootChecksumSectorSplit { sector: 12 },
ReadError::BackupBootRegionDiffers {
sector: 12,
detail: "x".to_string(),
},
ReadError::UnknownMinorRevision { minor: 3 },
ReadError::BadExtendedBootSignature {
sector: 1,
found: 0,
expected: EXTENDED_BOOT_SIGNATURE,
},
ReadError::ClusterOutOfRange { cluster: 9 },
ReadError::BadChainEntry {
cluster: 9,
entry: 0,
},
ReadError::BadClusterInChain {
cluster: BAD_CLUSTER,
},
ReadError::ChainTooLong {
start: 2,
clusters: 4,
},
ReadError::StreamTooShort {
start: 2,
declared: 8,
held: 4,
},
ReadError::BadReservedEntry {
index: 1,
found: 0,
expected: 1,
},
ReadError::MissingResident { resident: "x" },
ReadError::UpcaseChecksumMismatch {
computed: 1,
stored: 2,
},
ReadError::UpcaseTooLong {
bytes: 1 << 40,
limit: MAX_UPCASE_BYTES,
},
ReadError::BitmapWrongSize {
bytes: 1,
clusters: 2,
},
ReadError::SetChecksumMismatch {
index: 0,
computed: 1,
stored: 2,
},
ReadError::IncompleteEntrySet {
index: 0,
detail: "x".to_string(),
},
ReadError::StraySecondaryEntry { index: 0 },
ReadError::UnknownCriticalEntry {
index: 0,
entry_type: 0x9F,
},
ReadError::IllFormedName { index: 0 },
ReadError::NameHashMismatch {
index: 0,
computed: 1,
stored: 2,
},
ReadError::HostileName { index: 0 },
ReadError::ExcessNameEntries {
want: 1,
have: 2,
index: 0,
},
ReadError::MisplacedRootEntry {
index: 0,
entry_type: "x",
},
ReadError::DuplicateRootEntry {
index: 0,
entry_type: "x",
},
ReadError::LabelTooLong {
count: 200,
limit: MAX_LABEL_UNITS,
},
ReadError::LabelNulUnit,
ReadError::EntriesAfterEnd { index: 0 },
ReadError::DirectoryWithoutAllocation { index: 0 },
ReadError::StreamWithoutAllocation {
index: 0,
declared: 9_000,
},
ReadError::AllocationWithoutLength {
index: 0,
first_cluster: 5,
},
ReadError::StreamPastHeap {
declared: 1 << 40,
limit: 1 << 20,
},
ReadError::DirectoryTooLong {
index: 0,
declared: 1 << 30,
limit: MAX_DIRECTORY_BYTES,
},
ReadError::DirectoryLengthNotClusters {
index: 0,
declared: 1,
bytes_per_cluster: 4096,
},
ReadError::ReservedAttributes {
index: 0,
bits: 0xF008,
},
ReadError::AllocationNotPossible { index: 0 },
ReadError::MalformedTimestamp {
index: 0,
field: "creation time",
},
ReadError::ValidLengthPastEnd {
valid: 2,
declared: 1,
},
ReadError::ValidLengthTrails {
valid: 1,
declared: 2,
},
ReadError::ClusterNotAllocated { cluster: 2 },
ReadError::LostClusters { count: 1, first: 2 },
ReadError::CrossLinkedCluster { cluster: 2 },
ReadError::PercentInUseOutOfRange { stated: 200 },
ReadError::PercentInUseStale {
stated: 4,
in_use: 10,
clusters: 15_872,
actual: 0,
},
ReadError::VolumeDirty,
ReadError::MediaFailure,
ReadError::NotFound {
path: b"/x".to_vec(),
},
ReadError::NotADirectory {
path: b"/x".to_vec(),
},
ReadError::FileTooLarge { size: 2, limit: 1 },
ReadError::PathTooLong { limit: MAX_PATH },
ReadError::WalkTooLarge { limit: 1 },
];
for err in all {
let anomaly = err.anomaly();
assert!(!anomaly.detail.is_empty(), "{err:?}");
let finding = anomaly.to_finding(512);
assert_eq!(finding.family, Family::ExFat);
assert_eq!(finding.category, anomaly.category.as_str());
}
}
#[test]
fn every_category_names_itself() {
for category in [
Category::BootRegion,
Category::AllocationTable,
Category::AllocationBitmap,
Category::UpcaseTable,
Category::Directory,
] {
assert!(!category.as_str().is_empty());
}
}
fn bytes_u64(bytes: &[u8], at: usize) -> u64 {
u64::from_le_bytes(bytes[at..at + 8].try_into().expect("eight bytes"))
}
#[test]
fn the_recommended_table_is_what_a_volume_this_crate_wrote_folds_through() {
let bytes = image();
let r = reader(&bytes);
let recommended = UpcaseTable::recommended();
assert_eq!(r.upcase().folded_units(), recommended.folded_units());
for unit in [b'a' as u16, 0x00E9, 0x03B1, 0x0430, 0x00DF] {
assert_eq!(r.upcase().fold_unit(unit), recommended.fold_unit(unit));
}
assert_eq!(RECOMMENDED_UPCASE_TABLE.len(), 2918);
assert_eq!(BOOT_CHECKSUM_SKIPS.len(), 3);
}
}