use std::io::{Read, Seek, SeekFrom, Write};
use std::ops::ControlFlow;
use crate::bytes::get_u16;
use crate::fidelity::Synthesis;
use crate::finding::{Family, Finding, Findings, Severity};
use crate::io::{Bounded, offset_of, read_exact_at};
use crate::path::{is_hostile_component, is_reserved_name_char};
use crate::policy::MAX_PATH;
use crate::policy::{Limits, ReadPolicy};
use crate::time::{DosTimestamp, Timestamp};
use crate::tree::{Attributes, Bound, Child, FsTree, NodeKind, TreeEntry, TreeError, Usage};
use super::charset::ShortNameCharset;
use super::geometry::{
FatLayout, FatType, MAX_BYTES_PER_CLUSTER, MAX_CLUSTERS_FAT12, MIN_CLUSTERS_FAT16,
layout_from_boot,
};
use super::model::{MAX_DIRECTORY_BYTES, MAX_DIRECTORY_ENTRIES};
use super::ondisk::{
Attributes as DirAttributes, BootSector, BootSectorTail, DIR_ENTRY_SIZE, DirEntry, FsInfo,
LFN_CHARS_PER_ENTRY, LFN_LAST_ENTRY, LFN_MAX_ENTRIES, LFN_PADDING, LfnEntry, NAME_DELETED,
NAME_END, NAME_LEADING_E5, ParseError, VOLUME_DIRTY,
};
use super::table;
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub enum Category {
BootSector,
InfoSector,
AllocationTable,
Directory,
Source,
}
impl Category {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Category::BootSector => "boot sector",
Category::InfoSector => "information sector",
Category::AllocationTable => "allocation table",
Category::Directory => "directory",
Category::Source => "source",
}
}
}
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<u32>,
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),
}
}
}
#[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 is_source_failure(&self) -> bool {
self.category == Category::Source
}
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::Fat,
category.as_str(),
&[
("cluster", cluster.map(u64::from)),
("sector", sector.map(u64::from)),
("entry", entry.map(u64::from)),
],
sector.map(u64::from),
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("{field} = {value} is not a value a FAT volume's parameter block carries")]
#[non_exhaustive]
BadBootSector {
field: &'static str,
value: u64,
},
#[error(
"a count of {clusters} clusters is FAT16 to the specification and to Linux and FAT12 \
to Windows; the two follow its chains through tables of different entry widths"
)]
#[non_exhaustive]
AmbiguousClusterCount {
clusters: u32,
},
#[error(
"the volume's clusters are {bytes} bytes, past the 32768 the format advises a cluster \
never exceed"
)]
#[non_exhaustive]
LargeCluster {
bytes: u32,
},
#[error(
"the directory at entry {index} records a length of {size} bytes, where a directory records none"
)]
#[non_exhaustive]
DirectoryWithSize {
index: u32,
size: u32,
},
#[error(
"entry {index} carries the volume-label and directory attributes together, which is \
neither a label nor a directory"
)]
#[non_exhaustive]
LabelWithDirectoryAttribute {
index: u32,
},
#[error("entry {index} is a second volume label, and the first is the volume's")]
#[non_exhaustive]
SecondVolumeLabel {
index: u32,
},
#[error("entry {index} is a volume label beginning with a space")]
#[non_exhaustive]
LabelBeginsWithSpace {
index: u32,
},
#[error("the free-cluster hint is {stated}, more clusters than this volume's {clusters}")]
#[non_exhaustive]
FreeCountOutOfRange {
stated: u32,
clusters: u32,
},
#[error("the free-cluster hint is {stated} and the table marks {counted} clusters free")]
#[non_exhaustive]
FreeCountStale {
stated: u32,
counted: u32,
},
#[error("the long name ending at entry {index} is not padded the way the format pads one")]
#[non_exhaustive]
LongNamePadding {
index: u32,
},
#[error("cluster {cluster} is not a cluster this volume has")]
#[non_exhaustive]
ClusterOutOfRange {
cluster: u32,
},
#[error("sector {sector} is past the volume's {total_sectors} sectors")]
#[non_exhaustive]
SectorOutOfRange {
sector: u32,
total_sectors: u32,
},
#[error(
"the long name ending at entry {index} holds {units} UTF-16 units, past the format's 255"
)]
#[non_exhaustive]
LongNameTooLong {
index: u32,
units: usize,
},
#[error("the table entry for cluster {cluster} is {entry:#x}, 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 chain from cluster {start} ends before byte {read} of the {size} its entry records")]
#[non_exhaustive]
ChainTooShort {
start: u32,
size: u64,
read: u64,
},
#[error(
"file allocation table {copy} holds {other:#x} for cluster {cluster} where table 0 \
holds {first:#x}"
)]
#[non_exhaustive]
TableMismatch {
copy: u32,
cluster: u32,
first: u32,
other: u32,
},
#[error("file allocation table {copy} differs from table 0 in the padding past its last entry")]
#[non_exhaustive]
TablePaddingMismatch {
copy: u32,
},
#[error("table entry {index} is {found:#x} where the format defines {expected:#x}")]
#[non_exhaustive]
BadReservedEntry {
index: u32,
found: u32,
expected: u32,
},
#[error("{}", crate::finding::NOT_CLEANLY_UNMOUNTED)]
VolumeDirty,
#[error("{}", crate::finding::MEDIUM_FAILURE)]
MediaFailure,
#[error("the backup boot sector at sector {sector} is not a copy of sector 0")]
#[non_exhaustive]
BackupBootSectorDiffers {
sector: u32,
},
#[error("sector {sector} is named as the information sector and does not hold one")]
#[non_exhaustive]
BadInfoSector {
sector: u32,
},
#[error(
"the long name before entry {index} checksums to {found:#04x} and its short name to \
{expected:#04x}"
)]
#[non_exhaustive]
LongNameChecksum {
index: u32,
found: u8,
expected: u8,
},
#[error("the long-name entries ending at entry {index} do not form a complete run")]
#[non_exhaustive]
OrphanedLongName {
index: u32,
},
#[error("the long name at entry {index} is not well-formed UTF-16")]
#[non_exhaustive]
IllFormedLongName {
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(
"the short name at entry {index} carries byte {byte:#04x}, above ASCII, and this \
volume records no code page; name one to interpret it"
)]
#[non_exhaustive]
UninterpretedShortName {
index: u32,
byte: u8,
},
#[error("the name at entry {index} is one no directory can hold")]
#[non_exhaustive]
HostileName {
index: u32,
},
#[error(
"the {field} name at entry {index} carries {code:#06x}, a character the format \
reserves in it"
)]
#[non_exhaustive]
ReservedCharacter {
index: u32,
field: &'static str,
code: u32,
},
#[error(
"entry {index} carries a name entry {first} carries too, once case is folded, so a \
lookup reaches only the first"
)]
#[non_exhaustive]
IndistinguishableNames {
index: u32,
first: u32,
},
#[error(
"a directory entry names the directory at cluster {cluster}, which the tree reaches \
by another name as well"
)]
#[non_exhaustive]
RepeatedDirectory {
cluster: u32,
},
#[error("the entry at {index} records {size} bytes and no first cluster")]
#[non_exhaustive]
SizeWithoutAllocation {
index: u32,
size: u32,
},
#[error("{detail}")]
#[non_exhaustive]
BadDotEntry {
detail: String,
},
#[error(
"{}the `{name}` entry names cluster {found} where the format requires {expected}",
if path.is_empty() { String::new() } else { format!("{}: ", crate::escape::printable(path)) }
)]
#[non_exhaustive]
DotEntryTarget {
path: Vec<u8>,
name: &'static str,
found: u32,
expected: u32,
},
#[error("directory entry {index} follows the end marker and no reader reaches it")]
#[non_exhaustive]
EntriesAfterEnd {
index: u32,
},
#[error(
"the directory reaches entry {index}, past the {limit} bytes the format lets one \
directory be"
)]
#[non_exhaustive]
DirectoryTooLong {
index: u32,
limit: u64,
},
#[error("a volume label entry sits at entry {index} of a directory that is not the root")]
#[non_exhaustive]
MisplacedVolumeLabel {
index: u32,
},
#[error("{count} clusters are allocated and reached by no chain, the first at {first}")]
#[non_exhaustive]
LostClusters {
count: u32,
first: u32,
},
#[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 walk builds")]
#[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 at = |sector: Option<u32>, cluster: Option<u32>, entry: Option<u32>| Location {
sector,
cluster,
entry,
};
let (severity, category, location) = match self {
ReadError::Io {
kind: std::io::ErrorKind::UnexpectedEof,
..
} => (
Severity::Structural,
Category::BootSector,
Location::default(),
),
ReadError::Io { .. } => (Severity::Structural, Category::Source, Location::default()),
ReadError::Parse(_) | ReadError::BadBootSector { .. } => (
Severity::Structural,
Category::BootSector,
at(Some(0), None, None),
),
ReadError::AmbiguousClusterCount { .. } => (
Severity::Conformance,
Category::BootSector,
at(Some(0), None, None),
),
ReadError::LargeCluster { .. } => (
Severity::Cosmetic,
Category::BootSector,
at(Some(0), None, None),
),
ReadError::DirectoryWithSize { index, .. } | ReadError::LongNamePadding { index } => (
Severity::Cosmetic,
Category::Directory,
at(None, None, Some(*index)),
),
ReadError::LabelWithDirectoryAttribute { index }
| ReadError::SecondVolumeLabel { index }
| ReadError::LabelBeginsWithSpace { index } => (
Severity::Conformance,
Category::Directory,
at(None, None, Some(*index)),
),
ReadError::FreeCountStale { .. } => (
Severity::Cosmetic,
Category::InfoSector,
Location::default(),
),
ReadError::FreeCountOutOfRange { .. } => (
Severity::Conformance,
Category::InfoSector,
Location::default(),
),
ReadError::ClusterOutOfRange { cluster } => (
Severity::Structural,
Category::AllocationTable,
at(None, Some(*cluster), None),
),
ReadError::SectorOutOfRange { sector, .. } => (
Severity::Structural,
Category::BootSector,
at(Some(*sector), None, None),
),
ReadError::BadChainEntry { cluster, .. } => (
Severity::Structural,
Category::AllocationTable,
at(None, Some(*cluster), None),
),
ReadError::ChainTooLong { start, .. } | ReadError::ChainTooShort { start, .. } => (
Severity::Structural,
Category::AllocationTable,
at(None, Some(*start), None),
),
ReadError::TableMismatch { cluster, .. } => (
Severity::Integrity,
Category::AllocationTable,
at(None, Some(*cluster), None),
),
ReadError::TablePaddingMismatch { .. } => (
Severity::Cosmetic,
Category::AllocationTable,
Location::default(),
),
ReadError::BadReservedEntry { index, .. } => (
Severity::Conformance,
Category::AllocationTable,
at(None, Some(*index), None),
),
ReadError::VolumeDirty => (
Severity::Cosmetic,
Category::BootSector,
at(Some(0), None, None),
),
ReadError::MediaFailure => (
Severity::Cosmetic,
Category::AllocationTable,
at(None, Some(1), None),
),
ReadError::BackupBootSectorDiffers { sector } => (
Severity::Conformance,
Category::BootSector,
at(Some(*sector), None, None),
),
ReadError::BadInfoSector { sector } => (
Severity::Conformance,
Category::InfoSector,
at(Some(*sector), None, None),
),
ReadError::LongNameChecksum { index, .. } | ReadError::OrphanedLongName { index } => (
Severity::Integrity,
Category::Directory,
at(None, None, Some(*index)),
),
ReadError::LongNameTooLong { index, .. } => (
Severity::Conformance,
Category::Directory,
at(None, None, Some(*index)),
),
ReadError::HostileName { index } | ReadError::SizeWithoutAllocation { index, .. } => (
Severity::Structural,
Category::Directory,
at(None, None, Some(*index)),
),
ReadError::RepeatedDirectory { cluster } => (
Severity::Integrity,
Category::Directory,
at(None, Some(*cluster), None),
),
ReadError::IndistinguishableNames { index, .. } => (
Severity::Integrity,
Category::Directory,
at(None, None, Some(*index)),
),
ReadError::IllFormedLongName { index }
| ReadError::ReservedCharacter { index, .. }
| ReadError::UninterpretedShortName { index, .. }
| ReadError::EntriesAfterEnd { index }
| ReadError::DirectoryTooLong { index, .. }
| ReadError::MalformedTimestamp { index, .. }
| ReadError::MisplacedVolumeLabel { index } => (
Severity::Conformance,
Category::Directory,
at(None, None, Some(*index)),
),
ReadError::BadDotEntry { .. } => (
Severity::Conformance,
Category::Directory,
Location::default(),
),
ReadError::DotEntryTarget { .. } => (
Severity::Integrity,
Category::Directory,
Location::default(),
),
ReadError::LostClusters { first, .. } => (
Severity::Conformance,
Category::AllocationTable,
at(None, Some(*first), None),
),
ReadError::NotFound { .. } | ReadError::NotADirectory { .. } => (
Severity::Structural,
Category::Directory,
Location::default(),
),
ReadError::FileTooLarge { .. }
| ReadError::PathTooLong { .. }
| ReadError::WalkTooLarge { .. } => (
Severity::Structural,
Category::Directory,
Location::default(),
),
};
Anomaly {
severity,
category,
location,
detail: self.to_string(),
}
}
}
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 policy = self.policy;
let mut exact = None;
let mut exact_alias = None;
let mut folded = None;
let mut folded_alias = None;
self.parse_entries(
dir,
Placement::UNKNOWN,
&mut OnDeviation::Policy(policy),
|_, e, _| {
if e.name == name {
exact = Some(e.node);
return Ok(ControlFlow::Break(()));
}
if exact_alias.is_none() && e.short_name == name {
exact_alias = Some(e.node);
}
if folded.is_none() && e.name.eq_ignore_ascii_case(name) {
folded = Some(e.node);
}
if folded_alias.is_none() && e.short_name.eq_ignore_ascii_case(name) {
folded_alias = Some(e.node);
}
Ok(ControlFlow::Continue(()))
},
)?;
Ok(exact.or(exact_alias).or(folded).or(folded_alias))
}
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(),
}
}
}
pub(crate) struct Placed {
entry: WalkEntry,
parent: u32,
}
impl<R: Read + Seek> crate::walk::Walk for Reader<R> {
type Pending = Placed;
type Entry = Placed;
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 = match root.storage {
Storage::Chain(start) => vec![start],
Storage::None | Storage::RootRegion => Vec::new(),
};
Ok((self.walk_children(&root, &[], None)?, occupied))
}
fn resolve(&mut self, pending: Placed) -> Result<Placed, ReadError> {
Ok(pending)
}
fn descend_key(&self, placed: &Placed) -> Option<u32> {
let entry = &placed.entry;
if !entry.node.is_dir() {
return None;
}
match entry.node.storage {
Storage::Chain(start) => Some(start),
Storage::None | Storage::RootRegion => None,
}
}
fn children(&mut self, placed: &Placed) -> Result<Vec<Placed>, ReadError> {
self.walk_children(&placed.entry.node, &placed.entry.path, Some(placed.parent))
}
fn repeated(&mut self, placed: &Placed) -> Result<(), ReadError> {
let Storage::Chain(cluster) = placed.entry.node.storage else {
return Ok(());
};
let err = ReadError::RepeatedDirectory { cluster };
if self.policy.is_fatal(err.anomaly().severity) {
return Err(err);
}
Ok(())
}
fn too_large(limit: usize) -> ReadError {
ReadError::WalkTooLarge { limit }
}
}
impl From<ReadError> for TreeError {
fn from(err: ReadError) -> Self {
match err {
ReadError::Io { kind, message } => TreeError::Io { kind, message },
ReadError::FileTooLarge { .. } => TreeError::limit(Family::Fat, Bound::FileBytes, &err),
ReadError::PathTooLong { .. } => TreeError::limit(Family::Fat, Bound::PathBytes, &err),
ReadError::WalkTooLarge { .. } => TreeError::limit(Family::Fat, Bound::Entries, &err),
other => TreeError::Malformed {
family: Family::Fat,
detail: other.to_string(),
},
}
}
}
pub type ScanReport = crate::ScanReport<Anomaly>;
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Storage {
None,
Chain(u32),
RootRegion,
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct Times {
pub create: Option<Timestamp>,
pub access: Option<Timestamp>,
pub modify: Timestamp,
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct Node {
pub storage: Storage,
pub attributes: DirAttributes,
pub size: u32,
pub times: Option<Times>,
}
impl Node {
#[must_use]
pub const fn is_dir(&self) -> bool {
self.attributes.contains(DirAttributes::DIRECTORY)
|| matches!(self.storage, Storage::RootRegion)
}
#[must_use]
pub const fn is_volume_label(&self) -> bool {
!self.attributes.contains(DirAttributes::DIRECTORY)
&& self.attributes.contains(DirAttributes::VOLUME_ID)
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct Entry {
pub name: Vec<u8>,
pub short_name: Vec<u8>,
pub has_long_name: bool,
pub node: Node,
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct WalkEntry {
pub path: Vec<u8>,
pub node: Node,
}
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
#[non_exhaustive]
pub struct OpenOptions {
pub common: crate::OpenOptions,
pub charset: ShortNameCharset,
}
impl OpenOptions {
#[must_use]
pub const fn new() -> Self {
Self {
common: crate::OpenOptions::new(),
charset: ShortNameCharset::Verbatim,
}
}
#[must_use]
pub const fn base(mut self, base: u64) -> Self {
self.common = self.common.base(base);
self
}
#[must_use]
pub const fn len(mut self, len: u64) -> Self {
self.common = self.common.len(len);
self
}
#[must_use]
pub const fn policy(mut self, policy: ReadPolicy) -> Self {
self.common = self.common.policy(policy);
self
}
#[must_use]
pub const fn limits(mut self, limits: Limits) -> Self {
self.common = self.common.limits(limits);
self
}
#[must_use]
pub const fn common(mut self, common: crate::OpenOptions) -> Self {
self.common = common;
self
}
#[must_use]
pub const fn charset(mut self, charset: ShortNameCharset) -> Self {
self.charset = charset;
self
}
}
pub struct Reader<R> {
src: Bounded<R>,
base: u64,
boot: BootSector,
layout: FatLayout,
policy: ReadPolicy,
limits: Limits,
charset: ShortNameCharset,
open_anomalies: Vec<Anomaly>,
fat_window: Option<(u32, Vec<u8>)>,
volume_dirty: bool,
media_failure: bool,
chain_cursor: Option<(u32, u64, u32)>,
}
enum OnDeviation<'a> {
Policy(ReadPolicy),
Collect(&'a mut Findings<Anomaly>),
}
#[derive(Clone, Copy)]
struct Placement<'p> {
parent: Option<u32>,
path: Option<&'p [u8]>,
}
impl Placement<'_> {
const UNKNOWN: Self = Self {
parent: None,
path: None,
};
}
impl<'p> Placement<'p> {
const fn at(path: &'p [u8], parent: u32) -> Self {
Self {
parent: Some(parent),
path: Some(path),
}
}
}
const DOT_NAMES: [&[u8; 11]; 2] = [b". ", b".. "];
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(())
}
}
}
}
impl<R: Read + Seek> Reader<R> {
pub fn open(src: R) -> Result<Self, ReadError> {
Self::open_with(src, &OpenOptions::new())
}
pub fn open_with(src: R, options: &OpenOptions) -> Result<Self, ReadError> {
let mut src = Bounded::new(src, options.common.base, options.common.len);
let end = src.seek(SeekFrom::End(0))?;
let available = end.saturating_sub(options.common.base);
let sector = read_exact_at(&mut src, options.common.base, BootSector::SIZE)?;
let boot = BootSector::read_from(§or)?;
let layout = layout_from_boot(&boot, available).map_err(|d| ReadError::BadBootSector {
field: d.field,
value: d.value,
})?;
let mut open_anomalies = Vec::new();
if layout.fat_type == FatType::Fat16
&& layout.clusters > MAX_CLUSTERS_FAT12
&& layout.clusters < MIN_CLUSTERS_FAT16
{
let err = ReadError::AmbiguousClusterCount {
clusters: layout.clusters,
};
if options.common.policy.is_fatal(err.anomaly().severity) {
return Err(err);
}
open_anomalies.push(err.anomaly());
}
if layout.bytes_per_cluster() > MAX_BYTES_PER_CLUSTER {
open_anomalies.push(
ReadError::LargeCluster {
bytes: layout.bytes_per_cluster(),
}
.anomaly(),
);
}
let mut reader = Self {
src,
base: options.common.base,
boot,
layout,
policy: options.common.policy,
limits: options.common.limits,
charset: options.charset,
open_anomalies,
fat_window: None,
volume_dirty: false,
media_failure: false,
chain_cursor: None,
};
reader.read_volume_state();
Ok(reader)
}
fn read_volume_state(&mut self) {
let volume = self.boot.tail.volume();
let marked = volume.ext_boot_signature == super::ondisk::EXTENDED_BOOT_SIGNATURE
&& volume.reserved & VOLUME_DIRTY != 0;
let (clean, no_error) = table::status_bits(self.layout.fat_type);
let (cleared, failed) = match self.table_entry(1) {
Ok(entry) => (entry & clean != clean, entry & no_error != no_error),
Err(_) => (false, false),
};
self.volume_dirty = marked || cleared;
self.media_failure = failed;
}
#[must_use]
pub const fn layout(&self) -> &FatLayout {
&self.layout
}
#[must_use]
pub const fn boot_sector(&self) -> &BootSector {
&self.boot
}
#[must_use]
pub const fn fat_type(&self) -> FatType {
self.layout.fat_type
}
#[must_use]
pub const fn policy(&self) -> ReadPolicy {
self.policy
}
#[must_use]
pub const fn volume_dirty(&self) -> bool {
self.volume_dirty
}
#[must_use]
pub const fn media_failure(&self) -> bool {
self.media_failure
}
#[must_use]
pub const fn charset(&self) -> ShortNameCharset {
self.charset
}
#[must_use]
pub fn root(&self) -> Node {
let storage = match self.layout.fat32 {
Some(f) => Storage::Chain(f.root_cluster),
None => Storage::RootRegion,
};
Node {
storage,
attributes: DirAttributes::DIRECTORY,
size: 0,
times: None,
}
}
pub fn info_sector(&mut self) -> Result<Option<FsInfo>, ReadError> {
let Some(fat32) = self.layout.fat32 else {
return Ok(None);
};
let sector = u32::from(fat32.fs_info_sector);
let bytes = self.read_sectors(sector, 1)?;
match FsInfo::read_from(&bytes) {
Ok(info) => Ok(Some(info)),
Err(_) => Err(ReadError::BadInfoSector { sector }),
}
}
pub fn volume_label(&mut self) -> Result<Option<Vec<u8>>, ReadError> {
let root = self.root();
let mut found = None;
self.for_each_slot::<ReadError>(&root, |_, slot| {
let first = slot.entry.name[0];
if first == NAME_END {
return Ok(ControlFlow::Break(()));
}
if first == NAME_DELETED {
return Ok(ControlFlow::Continue(()));
}
if is_volume_label(slot.entry.attributes) {
found = Some(slot.entry.name);
return Ok(ControlFlow::Break(()));
}
Ok(ControlFlow::Continue(()))
})?;
if let Some(name) = found {
let label = volume_label(&name);
if label.is_empty() {
return Ok(None);
}
return Ok(Some(self.charset.decode(&label)));
}
let stored = self.boot.tail.volume().label;
if stored == super::ondisk::VolumeInfo::NO_NAME {
return Ok(None);
}
let trimmed = volume_label(&stored);
if trimmed.is_empty() {
return Ok(None);
}
Ok(Some(self.charset.decode(&trimmed)))
}
fn sector_offset(&self, sector: u32) -> Option<u64> {
offset_of(
self.base,
u64::from(sector),
u64::from(self.layout.bytes_per_sector),
)
}
fn read_sectors(&mut self, first: u32, count: u32) -> Result<Vec<u8>, ReadError> {
let out_of_range = || ReadError::SectorOutOfRange {
sector: first,
total_sectors: self.layout.total_sectors,
};
let end = first
.checked_add(count)
.filter(|end| *end <= self.layout.total_sectors)
.ok_or_else(out_of_range)?;
debug_assert!(end <= self.layout.total_sectors);
let offset = self.sector_offset(first).ok_or_else(out_of_range)?;
let len = count as usize * self.layout.bytes_per_sector as usize;
Ok(read_exact_at(&mut self.src, offset, len)?)
}
const fn table_window_sectors(&self, sector_in_table: u32) -> u32 {
if sector_in_table.saturating_add(1) < self.layout.fat_sectors {
2
} else {
1
}
}
fn table_entry(&mut self, cluster: u32) -> Result<u32, ReadError> {
let fat_type = self.layout.fat_type;
if cluster >= self.layout.max_table_entries() {
return Err(ReadError::ClusterOutOfRange { cluster });
}
let copy = self.active_fat();
let offset = table::entry_offset(fat_type, cluster);
let bytes_per_sector = u64::from(self.layout.bytes_per_sector);
let sector_in_table = u32::try_from(offset / bytes_per_sector)
.map_err(|_| ReadError::ClusterOutOfRange { cluster })?;
let within = (offset % bytes_per_sector) as usize;
let start = self
.layout
.fat_start_sector(copy)
.ok_or(ReadError::ClusterOutOfRange { cluster })?;
let sector = start
.checked_add(sector_in_table)
.ok_or(ReadError::ClusterOutOfRange { cluster })?;
let window_sectors = self.table_window_sectors(sector_in_table);
let need_reload = match &self.fat_window {
Some((at, buf)) => {
*at != sector || buf.len() < window_sectors as usize * bytes_per_sector as usize
}
None => true,
};
if need_reload {
let buf = self.read_sectors(sector, window_sectors)?;
self.fat_window = Some((sector, buf));
}
let (_, buf) = self.fat_window.as_ref().expect("just loaded");
table::read_entry(fat_type, &buf[within..], 0).map_or(
Err(ReadError::ClusterOutOfRange { cluster }),
|raw| {
if fat_type == FatType::Fat12 && cluster & 1 == 1 {
let pair = u32::from(get_u16(buf, within));
Ok(pair >> 4)
} else {
Ok(raw)
}
},
)
}
fn next_cluster(&mut self, cluster: u32) -> Result<Option<u32>, ReadError> {
let fat_type = self.layout.fat_type;
let entry = self.table_entry(cluster)?;
if table::is_end_of_chain(fat_type, entry) {
return Ok(None);
}
if !table::is_cluster(fat_type, entry) {
return Err(ReadError::BadChainEntry { cluster, entry });
}
if entry - 2 >= self.layout.clusters {
return Err(ReadError::ClusterOutOfRange { cluster: entry });
}
Ok(Some(entry))
}
fn cluster_at(&mut self, start: u32, index: u64) -> Result<Option<u32>, ReadError> {
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),
};
if start < 2 || start - 2 >= self.layout.clusters {
return Err(ReadError::ClusterOutOfRange { cluster: 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.clusters) {
return Err(ReadError::ChainTooLong {
start,
clusters: self.layout.clusters,
});
}
}
self.chain_cursor = Some((start, at, current));
Ok(Some(current))
}
pub fn chain(&mut self, start: u32) -> Result<Vec<u32>, ReadError> {
if start < 2 || start - 2 >= self.layout.clusters {
return Err(ReadError::ClusterOutOfRange { cluster: start });
}
let cap = self.limits.max_walk_entries;
let mut out = vec![start];
let mut current = start;
while let Some(next) = self.next_cluster(current)? {
if out.len() as u64 > u64::from(self.layout.clusters) {
return Err(ReadError::ChainTooLong {
start,
clusters: self.layout.clusters,
});
}
if out.len() >= cap {
return Err(ReadError::WalkTooLarge { limit: cap });
}
out.push(next);
current = next;
}
Ok(out)
}
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, self.layout.sectors_per_cluster)
}
fn for_each_slot<E: From<ReadError>>(
&mut self,
node: &Node,
mut visit: impl FnMut(&mut Self, Slot) -> Result<ControlFlow<()>, E>,
) -> Result<(), E> {
let entries_per_sector = (self.layout.bytes_per_sector as usize / DIR_ENTRY_SIZE).max(1);
let mut index = 0u32;
let mut next = match node.storage {
Storage::None => None,
Storage::RootRegion => self
.layout
.root_dir_start_sector()
.map(|first| (first, self.layout.root_dir_sectors, None)),
Storage::Chain(start) => Some((0, 0, Some(start))),
};
let mut visited = ClusterSet::new(self.layout.clusters);
if let Storage::Chain(start) = node.storage {
visited.insert(start);
}
let mut steps = 0u64;
while let Some((mut first, mut count, cluster)) = next {
if let Some(current) = cluster {
first = self
.layout
.cluster_start_sector(current)
.ok_or(ReadError::ClusterOutOfRange { cluster: current })?;
count = self.layout.sectors_per_cluster;
}
let bytes = self.read_sectors(first, count).map_err(E::from)?;
for (i, chunk) in bytes.as_chunks::<DIR_ENTRY_SIZE>().0.iter().enumerate() {
let Ok(entry) = DirEntry::read_from(chunk) else {
continue;
};
let slot = Slot {
entry,
index,
sector: first + (i / entries_per_sector) as u32,
};
index = index.saturating_add(1);
if visit(self, slot)?.is_break() {
return Ok(());
}
}
next = match cluster {
None => None,
Some(current) => match self.next_cluster(current).map_err(E::from)? {
None => None,
Some(following) => {
steps += 1;
let repeat = !visited.insert(following);
if repeat || steps > u64::from(self.layout.clusters) {
let Storage::Chain(start) = node.storage else {
unreachable!("only a chain steps between clusters")
};
return Err(E::from(ReadError::ChainTooLong {
start,
clusters: self.layout.clusters,
}));
}
Some((0, 0, Some(following)))
}
},
};
}
Ok(())
}
pub fn read_dir(&mut self, node: &Node) -> Result<Vec<Entry>, ReadError> {
let policy = self.policy;
self.parse_dir(node, Placement::UNKNOWN, &mut OnDeviation::Policy(policy))
}
fn parse_dir(
&mut self,
node: &Node,
placement: Placement<'_>,
deviations: &mut OnDeviation<'_>,
) -> Result<Vec<Entry>, ReadError> {
let cap = self.limits.max_walk_entries.min(self.max_names());
let mut out: Vec<Entry> = Vec::new();
let mut names: std::collections::HashMap<Vec<u8>, u32> = std::collections::HashMap::new();
let mut repeats = Vec::new();
self.parse_entries(node, placement, deviations, |_, entry, at| {
if out.len() >= cap {
return Err(ReadError::WalkTooLarge { limit: cap });
}
let index = at.entry.unwrap_or_default();
let keys = lookup_keys(&entry);
if let Some(&first) = keys.iter().find_map(|key| names.get(key)) {
repeats.push((at, ReadError::IndistinguishableNames { index, first }));
}
for key in keys {
names.entry(key).or_insert(index);
}
out.push(entry);
Ok(ControlFlow::Continue(()))
})?;
for (at, repeat) in repeats {
deviations.record(at, repeat)?;
}
Ok(out)
}
fn parse_entries(
&mut self,
node: &Node,
placement: Placement<'_>,
deviations: &mut OnDeviation<'_>,
mut each: impl FnMut(&mut Self, Entry, Location) -> Result<ControlFlow<()>, ReadError>,
) -> Result<(), ReadError> {
if !node.is_dir() {
return Err(ReadError::NotADirectory { path: Vec::new() });
}
let is_root = matches!(node.storage, Storage::RootRegion)
|| self
.layout
.fat32
.is_some_and(|f| node.storage == Storage::Chain(f.root_cluster));
let charset = self.charset;
let fat_type = self.layout.fat_type;
let mut pending = LongName::default();
let mut ended = false;
let mut reported_after_end = false;
let mut last_slot = None;
let mut slots = 0u32;
let mut stopped = false;
let mut labels = 0u32;
let own = match node.storage {
Storage::Chain(start) => start,
Storage::None | Storage::RootRegion => 0,
};
let shown = |path: Option<&[u8]>| {
path.map_or_else(String::new, |p| {
format!("{}: ", crate::escape::printable(p))
})
};
self.for_each_slot::<ReadError>(node, |reader, slot| {
let index = slot.index;
let at = Location {
sector: Some(slot.sector),
cluster: None,
entry: Some(index),
};
last_slot = Some((at, index));
slots = index + 1;
if u64::from(index) == MAX_DIRECTORY_ENTRIES {
deviations.record(
at,
ReadError::DirectoryTooLong {
index,
limit: MAX_DIRECTORY_BYTES,
},
)?;
}
let entry = slot.entry;
let first = entry.name[0];
if !is_root && let Some(&want) = DOT_NAMES.get(index as usize) {
let dot = if index == 0 { "." } else { ".." };
let is_dot = !ended
&& first != NAME_END
&& first != NAME_DELETED
&& !entry.attributes.is_long_name()
&& entry.name == *want;
if !is_dot {
deviations.record(
at,
ReadError::BadDotEntry {
detail: format!(
"{}entry {index} is not the `{dot}` entry the format puts there",
shown(placement.path)
),
},
)?;
} else {
if !entry.attributes.contains(DirAttributes::DIRECTORY) {
deviations.record(
at,
ReadError::BadDotEntry {
detail: format!(
"{}the `{dot}` entry does not carry the directory attribute",
shown(placement.path)
),
},
)?;
}
let expected = if index == 0 {
Some(own)
} else {
placement.parent
};
let found = first_cluster(&entry, fat_type);
if let Some(expected) = expected
&& found != expected
{
deviations.record(
at,
ReadError::DotEntryTarget {
path: placement.path.unwrap_or_default().to_vec(),
name: dot,
found,
expected,
},
)?;
}
}
}
if ended {
if first != NAME_END && !reported_after_end {
deviations.record(at, ReadError::EntriesAfterEnd { index })?;
reported_after_end = true;
}
return Ok(ControlFlow::Continue(()));
}
if first == NAME_END {
if !matches!(pending.take(), LongRun::None) {
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
ended = true;
return Ok(ControlFlow::Continue(()));
}
if first == NAME_DELETED {
if !matches!(pending.take(), LongRun::None) {
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
return Ok(ControlFlow::Continue(()));
}
if entry.attributes.is_long_name() {
let lfn = LfnEntry::read_from(&raw_bytes(&entry))?;
if pending.accept(&lfn) {
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
return Ok(ControlFlow::Continue(()));
}
let run = pending.take();
let short_name = render_short(&entry.name, entry.case_flags);
if entry.attributes.contains(DirAttributes::VOLUME_ID) {
if !is_volume_label(entry.attributes) {
deviations.record(at, ReadError::LabelWithDirectoryAttribute { index })?;
} else if !is_root {
deviations.record(at, ReadError::MisplacedVolumeLabel { index })?;
} else {
labels += 1;
if labels > 1 {
deviations.record(at, ReadError::SecondVolumeLabel { index })?;
}
if entry.name[0] == b' ' {
deviations.record(at, ReadError::LabelBeginsWithSpace { index })?;
}
}
if !matches!(run, LongRun::None) {
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
return Ok(ControlFlow::Continue(()));
}
if crate::path::is_dot_entry(&short_name) {
if !matches!(run, LongRun::None) {
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
if is_root || index >= 2 {
deviations.record(
at,
ReadError::BadDotEntry {
detail: format!(
"{}entry {index} is a `{}` entry, where the format puts none",
shown(placement.path),
crate::escape::printable(&short_name)
),
},
)?;
}
return Ok(ControlFlow::Continue(()));
}
let mut has_long_name = false;
let mut name = None;
match run {
LongRun::None => {}
LongRun::Incomplete => {
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
LongRun::Complete {
units,
checksum,
padded,
} => {
if !padded {
deviations.record(at, ReadError::LongNamePadding { index })?;
}
let expected = entry.lfn_checksum();
if checksum != expected {
deviations.record(
at,
ReadError::LongNameChecksum {
index,
found: checksum,
expected,
},
)?;
} else {
if units.len() > super::name::MAX_NAME_UNITS {
deviations.record(
at,
ReadError::LongNameTooLong {
index,
units: units.len(),
},
)?;
}
let (decoded, ill_formed) = decode_utf16(&units);
if ill_formed {
deviations.record(at, ReadError::IllFormedLongName { index })?;
}
has_long_name = true;
name = Some(decoded);
}
}
}
let name = match name {
Some(name) => name,
None => {
if let Some(byte) = short_name.iter().copied().find(|b| *b >= 0x80) {
let err = ReadError::UninterpretedShortName { index, byte };
if charset == ShortNameCharset::Verbatim {
deviations.record(at, err)?;
} else {
let mut anomaly = err.anomaly();
anomaly.severity = Severity::Cosmetic;
anomaly.detail = format!(
"the short name at entry {index} carries byte {byte:#04x}, \
above ASCII, read as code page {}",
charset.as_str()
);
if let OnDeviation::Collect(findings) = deviations {
anomaly.location = anomaly.location.or(at);
findings.push(anomaly);
}
}
}
charset.decode(&short_name)
}
};
if is_hostile_component(&name) {
deviations.record(at, ReadError::HostileName { index })?;
return Ok(ControlFlow::Continue(()));
}
if has_long_name
&& let Some(ch) = String::from_utf8_lossy(&name)
.chars()
.find(|&ch| is_reserved_name_char(ch))
{
deviations.record(
at,
ReadError::ReservedCharacter {
index,
field: "long",
code: u32::from(ch),
},
)?;
}
if let Some((_, &byte)) =
entry.name.iter().enumerate().find(|&(position, &byte)| {
super::name::is_reserved_short_byte_at(byte, position)
})
{
deviations.record(
at,
ReadError::ReservedCharacter {
index,
field: "short",
code: u32::from(byte),
},
)?;
}
check_times(&entry, index, at, deviations)?;
let node = node_of(&entry, reader.layout.fat_type);
if node.size != 0 && node.is_dir() {
deviations.record(
at,
ReadError::DirectoryWithSize {
index,
size: node.size,
},
)?;
} else if node.size != 0 && matches!(node.storage, Storage::None) {
deviations.record(
at,
ReadError::SizeWithoutAllocation {
index,
size: node.size,
},
)?;
}
let flow = each(
reader,
Entry {
name,
short_name: charset.decode(&short_name),
has_long_name,
node,
},
at,
)?;
stopped = flow.is_break();
Ok(flow)
})?;
if !is_root && !stopped {
for index in slots..2 {
let dot = if index == 0 { "." } else { ".." };
deviations.record(
Location {
entry: Some(index),
..Location::default()
},
ReadError::BadDotEntry {
detail: format!(
"{}the directory ends before its `{dot}` entry",
shown(placement.path)
),
},
)?;
}
}
if !matches!(pending.take(), LongRun::None)
&& let Some((at, index)) = last_slot
{
deviations.record(at, ReadError::OrphanedLongName { index })?;
}
Ok(())
}
pub fn lookup(&mut self, path: &[u8]) -> Result<Node, ReadError> {
crate::resolve::drive(self, path, true)
}
pub fn read_into(
&mut self,
node: &Node,
offset: u64,
buf: &mut [u8],
) -> Result<usize, ReadError> {
if node.is_dir() || node.is_volume_label() {
return Ok(0);
}
let Storage::Chain(start) = node.storage else {
return Ok(0);
};
let size = u64::from(node.size);
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;
let index = at / bytes_per_cluster;
let within = (at % bytes_per_cluster) as usize;
let Some(cluster) = self.cluster_at(start, index)? else {
return Err(ReadError::ChainTooShort {
start,
size,
read: at,
});
};
let bytes = self.read_cluster(cluster)?;
let take = (bytes.len() - within).min(want - done);
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> {
let size = u64::from(node.size);
if size > self.limits.max_file_bytes {
return Err(ReadError::FileTooLarge {
size,
limit: self.limits.max_file_bytes,
});
}
Ok(size)
}
pub fn read_data_to(&mut self, node: &Node, mut out: impl Write) -> Result<u64, ReadError> {
if node.is_dir() || node.is_volume_label() {
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::ChainTooShort {
start: match node.storage {
Storage::Chain(start) => start,
_ => 0,
},
size,
read: 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, placed: Placed| visit(reader, placed.entry))
}
fn walk_children(
&mut self,
node: &Node,
prefix: &[u8],
parent: Option<u32>,
) -> Result<Vec<Placed>, ReadError> {
let policy = self.policy;
let placement = match parent {
Some(parent) => Placement::at(prefix, parent),
None => Placement {
parent: None,
path: Some(prefix),
},
};
let mut entries = self.parse_dir(node, placement, &mut OnDeviation::Policy(policy))?;
entries.sort_by(|a, b| a.name.cmp(&b.name));
let here = self.parent_mark(node);
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(Placed {
entry: WalkEntry { path, node: e.node },
parent: here,
});
}
Ok(children)
}
fn parent_mark(&self, node: &Node) -> u32 {
match (node.storage, self.layout.fat32) {
(Storage::Chain(start), Some(f)) if start == f.root_cluster => 0,
(Storage::Chain(start), _) => start,
(Storage::None | Storage::RootRegion, _) => 0,
}
}
fn max_names(&self) -> usize {
let root = u64::from(self.layout.root_entries);
let data = u64::from(self.layout.clusters) * u64::from(self.layout.bytes_per_cluster())
/ DIR_ENTRY_SIZE as u64;
usize::try_from(root.saturating_add(data)).unwrap_or(usize::MAX)
}
pub fn verify_tables(&mut self) -> Result<(), ReadError> {
match self.table_faults()?.into_iter().next() {
Some(err) => Err(err),
None => Ok(()),
}
}
fn table_faults(&mut self) -> Result<Vec<ReadError>, ReadError> {
let mut out = Vec::new();
if self.mirroring_disabled() || self.layout.fats < 2 {
return Ok(out);
}
let fat_type = self.layout.fat_type;
let sectors = self.layout.fat_sectors;
let bytes_per_sector = self.layout.bytes_per_sector;
let highest = self.layout.clusters + 1;
let live_bytes = table::entry_offset(fat_type, highest) + table::entry_span(fat_type);
for copy in 1..self.layout.fats {
let mut padding_only = false;
let mut found = false;
let (Some(first_start), Some(copy_start)) = (
self.layout.fat_start_sector(0),
self.layout.fat_start_sector(copy),
) else {
continue;
};
let batch = (1u32 << 20) / bytes_per_sector.max(1);
let mut s = 0u32;
while s < sectors {
let count = batch.clamp(1, sectors - s);
let a = self.read_sectors(first_start + s, count)?;
let b = self.read_sectors(copy_start + s, count)?;
if a == b {
s += count;
continue;
}
let base = u64::from(s) * u64::from(bytes_per_sector);
let at = a
.iter()
.zip(b.iter())
.position(|(x, y)| x != y)
.expect("the batches differ") as u64
+ base;
if at >= live_bytes {
padding_only = true;
s += count;
continue;
}
let (candidate, shared) = match fat_type {
FatType::Fat12 => {
let even = (at * 2 / 3) as u32;
let odd = (at % 3 == 1 && even < highest).then_some(even + 1);
(even, odd)
}
FatType::Fat16 => ((at / 2) as u32, None),
FatType::Fat32 => ((at / 4) as u32, None),
};
let mut mismatch = None;
for cluster in [Some(candidate), shared].into_iter().flatten() {
let first = self.table_entry_in(0, cluster)?;
let other = self.table_entry_in(copy, cluster)?;
if first != other {
mismatch = Some((cluster, first, other));
break;
}
}
let (cluster, first, other) = match mismatch {
Some(found) => found,
None => (
candidate,
self.table_entry_in(0, candidate)?,
self.table_entry_in(copy, candidate)?,
),
};
out.push(ReadError::TableMismatch {
copy,
cluster,
first,
other,
});
found = true;
break;
}
if !found && padding_only {
out.push(ReadError::TablePaddingMismatch { copy });
}
}
Ok(out)
}
fn table_entry_in(&mut self, index: u32, cluster: u32) -> Result<u32, ReadError> {
let fat_type = self.layout.fat_type;
if cluster >= self.layout.max_table_entries() {
return Err(ReadError::ClusterOutOfRange { cluster });
}
let offset = table::entry_offset(fat_type, cluster);
let bytes_per_sector = u64::from(self.layout.bytes_per_sector);
let sector_in_table = u32::try_from(offset / bytes_per_sector)
.map_err(|_| ReadError::ClusterOutOfRange { cluster })?;
let within = (offset % bytes_per_sector) as usize;
let first = self
.layout
.fat_start_sector(index)
.ok_or(ReadError::ClusterOutOfRange { cluster })?;
let sector = first
.checked_add(sector_in_table)
.ok_or(ReadError::ClusterOutOfRange { cluster })?;
let count = self.table_window_sectors(sector_in_table);
let bytes = self.read_sectors(sector, count)?;
let raw = table::read_entry(fat_type, &bytes[within..], 0)
.ok_or(ReadError::ClusterOutOfRange { cluster })?;
if fat_type == FatType::Fat12 && cluster & 1 == 1 {
Ok(u32::from(get_u16(&bytes, within)) >> 4)
} else {
Ok(raw)
}
}
const fn mirroring_disabled(&self) -> bool {
match self.boot.tail {
BootSectorTail::Fat32 { params, .. } => params.ext_flags & 0x0080 != 0,
BootSectorTail::Fat1216 { .. } => false,
}
}
const fn active_fat(&self) -> u32 {
match self.boot.tail {
BootSectorTail::Fat32 { params, .. } if params.ext_flags & 0x0080 != 0 => {
let index = (params.ext_flags & 0x000F) as u32;
if index < self.layout.fats { index } else { 0 }
}
_ => 0,
}
}
#[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);
}
if self.volume_dirty {
findings.push(ReadError::VolumeDirty.anomaly());
}
if self.media_failure {
findings.push(ReadError::MediaFailure.anomaly());
}
self.scan_reserved(&mut findings);
self.scan_tables(&mut findings);
let reached = self.scan_tree(&mut findings);
let reached = reached.filter(|_| !findings.met_source_failure());
self.scan_usage(&mut findings, reached.as_ref());
findings.into_report(self.layout.bytes_per_sector)
}
fn scan_reserved(&mut self, findings: &mut Findings<Anomaly>) {
let Some(fat32) = self.layout.fat32 else {
return;
};
if let BootSectorTail::Fat32 { params, .. } = self.boot.tail
&& params.version != 0
{
findings.push(Anomaly {
severity: Severity::Conformance,
category: Category::BootSector,
location: Location::default(),
detail: format!(
"BPB_FSVer is {:#06x}: zero is the only FAT32 version defined, and a \
driver refuses a volume whose version it does not know",
params.version
),
});
}
if let Some(backup) = fat32.backup_boot_sector {
let backup = u32::from(backup);
match (self.read_sectors(0, 1), self.read_sectors(backup, 1)) {
(Ok(mut primary), Ok(mut copy)) => {
let dirty_at = self.boot.tail.volume_offset() + 1;
for sector in [&mut primary, &mut copy] {
if let Some(byte) = sector.get_mut(dirty_at) {
*byte &= !VOLUME_DIRTY;
}
}
if primary != copy {
findings
.push(ReadError::BackupBootSectorDiffers { sector: backup }.anomaly());
}
}
(Err(e), _) | (_, Err(e)) => findings.push(e.anomaly()),
}
}
let info_sector = u32::from(fat32.fs_info_sector);
if let Ok(bytes) = self.read_sectors(info_sector, 1)
&& let Some(low) = bytes
.get(FsInfo::TRAIL_OFFSET..FsInfo::TRAIL_OFFSET + 2)
.map(|b| get_u16(b, 0))
&& low != 0
{
findings.push(Anomaly {
severity: Severity::Cosmetic,
category: Category::InfoSector,
location: Location {
sector: Some(info_sector),
..Location::default()
},
detail: format!(
"the information sector's trailing signature carries {low:#06x} where the \
format defines two zero bytes"
),
});
}
match self.info_sector() {
Ok(Some(info)) => {
if let Some(next) = info.next_free_cluster
&& next >= self.layout.clusters + 2
{
findings.push(Anomaly {
severity: Severity::Cosmetic,
category: Category::InfoSector,
location: Location {
sector: Some(u32::from(fat32.fs_info_sector)),
cluster: Some(next),
entry: None,
},
detail: format!(
"the next-free hint names cluster {next}, which this volume does \
not have"
),
});
}
}
Ok(None) => {}
Err(e) => findings.push(e.anomaly()),
}
}
fn scan_tables(&mut self, findings: &mut Findings<Anomaly>) {
let fat_type = self.layout.fat_type;
let expected_media = table::media_entry(fat_type, self.boot.media);
let expected_tail = table::tail_entry(fat_type);
let (clean, no_error) = table::status_bits(fat_type);
for (index, expected, state) in [
(0u32, expected_media, 0),
(1, expected_tail, clean | no_error),
] {
match self.table_entry(index) {
Ok(found) if found | state != expected => findings.push(
ReadError::BadReservedEntry {
index,
found,
expected,
}
.anomaly(),
),
Ok(_) => {}
Err(e) => findings.push(e.anomaly()),
}
}
if self.mirroring_disabled() {
let named = match self.boot.tail {
BootSectorTail::Fat32 { params, .. } => u32::from(params.ext_flags & 0x000F),
BootSectorTail::Fat1216 { .. } => 0,
};
findings.push(Anomaly {
severity: Severity::Conformance,
category: Category::AllocationTable,
location: Location::default(),
detail: format!(
"BPB_ExtFlags switches mirroring off, so only table {named} is live and \
the copies are not obliged to agree"
),
});
if named >= self.layout.fats {
findings.push(Anomaly {
severity: Severity::Integrity,
category: Category::AllocationTable,
location: Location::default(),
detail: format!(
"BPB_ExtFlags names table {named} as the live one, but the volume \
has {} — chains are resolved through table 0 instead",
self.layout.fats
),
});
}
return;
}
match self.table_faults() {
Ok(faults) => {
for fault in faults {
findings.push(fault.anomaly());
}
}
Err(e) => findings.push(e.anomaly()),
}
}
fn scan_tree(&mut self, findings: &mut Findings<Anomaly>) -> Option<ClusterSet> {
let mut reached = ClusterSet::new(self.layout.clusters);
let mut visited = ClusterSet::new(self.layout.clusters);
let mut queue = vec![(Vec::new(), self.root(), None)];
if let Storage::Chain(start) = self.root().storage {
visited.insert(start);
}
let mut names = 0usize;
let cap = self.limits.max_walk_entries.min(self.max_names());
while let Some((label, node, parent)) = queue.pop() {
if findings.is_full() {
return None;
}
let claimed = self.claim_chain(&node, &label, &mut reached, findings);
if node.is_dir() {
let mut deviations = OnDeviation::Collect(findings);
let placement = Placement {
parent,
path: Some(&label),
};
let entries = match self.parse_dir(&node, placement, &mut deviations) {
Ok(entries) => entries,
Err(e @ ReadError::WalkTooLarge { .. }) => {
findings.push(e.anomaly());
return None;
}
Err(e) => {
findings.push(e.anomaly());
continue;
}
};
let here = self.parent_mark(&node);
for entry in entries {
names += 1;
if names > cap {
findings.push(ReadError::WalkTooLarge { limit: cap }.anomaly());
return None;
}
let child = crate::walk::label(&label, &entry.name);
let descend = match entry.node.storage {
Storage::Chain(start) if entry.node.is_dir() => visited.insert(start),
_ => false,
};
if descend || !entry.node.is_dir() {
queue.push((child, entry.node, Some(here)));
}
}
} else if let Some(chain_bytes) = claimed {
let size = u64::from(node.size);
let bpc = u64::from(self.layout.bytes_per_cluster());
let need = size.div_ceil(bpc.max(1)) * bpc;
if chain_bytes != need {
findings.push(Anomaly {
severity: Severity::Conformance,
category: Category::AllocationTable,
location: Location::default(),
detail: format!(
"{}: a length of {size} bytes needs {need} bytes of clusters and \
its chain holds {chain_bytes}",
crate::escape::printable(&label)
),
});
}
}
}
Some(reached)
}
fn claim_chain(
&mut self,
node: &Node,
path: &[u8],
reached: &mut ClusterSet,
findings: &mut Findings<Anomaly>,
) -> Option<u64> {
let Storage::Chain(start) = node.storage else {
return None;
};
let mut current = start;
let mut count = 0u64;
let mut own = std::collections::HashSet::new();
loop {
if !reached.insert(current) {
let detail = if own.contains(¤t) {
format!(
"{}: the chain from cluster {start} returns to cluster {current}, \
and a chain that loops never ends",
crate::escape::printable(path)
)
} else {
format!(
"{}: cluster {current} is already part of another chain",
crate::escape::printable(path)
)
};
findings.push(Anomaly {
severity: Severity::Structural,
category: Category::AllocationTable,
location: Location {
cluster: Some(current),
..Location::default()
},
detail,
});
return None;
}
own.insert(current);
count += 1;
if count > u64::from(self.layout.clusters) {
findings.push(
ReadError::ChainTooLong {
start,
clusters: self.layout.clusters,
}
.anomaly(),
);
return None;
}
match self.next_cluster(current) {
Ok(Some(next)) => current = next,
Ok(None) => break,
Err(e) => {
findings.push(e.anomaly());
return None;
}
}
}
Some(count * u64::from(self.layout.bytes_per_cluster()))
}
fn census(&mut self, reached: Option<&ClusterSet>) -> Census {
let bad = table::bad_cluster(self.layout.fat_type);
let mut census = Census {
free: 0,
lost: 0,
first_lost: None,
failed: None,
};
for cluster in 2..self.layout.clusters + 2 {
let entry = match self.table_entry(cluster) {
Ok(entry) => entry,
Err(e) => {
census.failed = Some(e);
break;
}
};
if entry == table::FREE {
census.free += 1;
continue;
}
if entry == bad || reached.is_none_or(|reached| reached.contains(cluster)) {
continue;
}
census.lost += 1;
census.first_lost.get_or_insert(cluster);
}
census
}
fn scan_usage(&mut self, findings: &mut Findings<Anomaly>, reached: Option<&ClusterSet>) {
let Census {
free,
lost,
first_lost: first,
failed,
} = self.census(reached);
let whole = failed.is_none();
if let Some(first) = first {
findings.push(ReadError::LostClusters { count: lost, first }.anomaly());
}
let Ok(Some(info)) = self.info_sector() else {
return;
};
let Some(stated) = info.free_clusters else {
return;
};
let sector = self.layout.fat32.map(|f| u32::from(f.fs_info_sector));
let at = Location {
sector,
..Location::default()
};
let err = if stated > self.layout.clusters {
ReadError::FreeCountOutOfRange {
stated,
clusters: self.layout.clusters,
}
} else if whole && stated != free {
ReadError::FreeCountStale {
stated,
counted: free,
}
} else {
return;
};
let mut anomaly = err.anomaly();
anomaly.location = anomaly.location.or(at);
findings.push(anomaly);
}
}
struct Census {
free: u32,
lost: u32,
first_lost: Option<u32>,
failed: Option<ReadError>,
}
struct Slot {
entry: DirEntry,
index: u32,
sector: u32,
}
struct ClusterSet {
bits: Vec<u64>,
clusters: u32,
}
impl ClusterSet {
fn new(clusters: u32) -> Self {
let highest = clusters as usize + 2;
Self {
bits: vec![0u64; highest.div_ceil(64)],
clusters,
}
}
fn insert(&mut self, cluster: u32) -> bool {
if cluster < 2 || cluster - 2 >= self.clusters {
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 {
if cluster < 2 || cluster - 2 >= self.clusters {
return false;
}
self.bits[cluster as usize / 64] & (1 << (cluster as usize % 64)) != 0
}
}
enum LongRun {
None,
Incomplete,
Complete {
units: Vec<u16>,
checksum: u8,
padded: bool,
},
}
#[derive(Default)]
struct LongName {
chunks: Vec<Option<[u16; LFN_CHARS_PER_ENTRY]>>,
checksum: Option<u8>,
broken: bool,
}
impl LongName {
fn clear(&mut self) {
self.chunks.clear();
self.checksum = None;
self.broken = false;
}
fn accept(&mut self, entry: &LfnEntry) -> bool {
let ordinal = usize::from(entry.order & !LFN_LAST_ENTRY);
let mut discarded = false;
if entry.order & LFN_LAST_ENTRY != 0 {
discarded = self.is_live();
self.clear();
if ordinal == 0 || ordinal > LFN_MAX_ENTRIES {
self.broken = true;
return discarded;
}
self.chunks = vec![None; ordinal];
self.checksum = Some(entry.checksum);
}
if ordinal == 0 || ordinal > self.chunks.len() || self.checksum != Some(entry.checksum) {
self.broken = true;
return discarded;
}
if self.chunks[ordinal - 1].is_some() {
self.broken = true;
return discarded;
}
self.chunks[ordinal - 1] = Some(entry.name);
discarded
}
fn is_live(&self) -> bool {
!self.chunks.is_empty() || self.broken
}
fn take(&mut self) -> LongRun {
let run = if self.chunks.is_empty() && !self.broken {
LongRun::None
} else if self.broken || self.chunks.iter().any(Option::is_none) {
LongRun::Incomplete
} else {
let mut units = Vec::with_capacity(self.chunks.len() * LFN_CHARS_PER_ENTRY);
for chunk in self.chunks.iter().flatten() {
units.extend_from_slice(chunk);
}
let mut padded = true;
if let Some(end) = units.iter().position(|u| *u == 0 || *u == LFN_PADDING) {
let after = if units[end] == 0 { end + 1 } else { end };
padded = units[end] == 0 && units[after..].iter().all(|u| *u == LFN_PADDING);
units.truncate(end);
}
match self.checksum {
Some(checksum) => LongRun::Complete {
units,
checksum,
padded,
},
None => LongRun::Incomplete,
}
};
self.clear();
run
}
}
fn raw_bytes(entry: &DirEntry) -> [u8; DIR_ENTRY_SIZE] {
let mut buf = [0u8; DIR_ENTRY_SIZE];
let _ = entry.write_to(&mut buf);
buf
}
const NT_LOWER_BASE: u8 = 0x08;
const NT_LOWER_EXT: u8 = 0x10;
fn render_short(name: &[u8; 11], case_flags: u8) -> Vec<u8> {
let fold = |bytes: &mut Vec<u8>, lower: bool| {
if lower {
bytes.make_ascii_lowercase();
}
};
let mut base = name[..8].to_vec();
while base.last() == Some(&b' ') {
base.pop();
}
if base.first() == Some(&NAME_LEADING_E5) {
base[0] = NAME_DELETED;
}
fold(&mut base, case_flags & NT_LOWER_BASE != 0);
let mut ext = name[8..].to_vec();
while ext.last() == Some(&b' ') {
ext.pop();
}
fold(&mut ext, case_flags & NT_LOWER_EXT != 0);
if ext.is_empty() {
base
} else {
base.push(b'.');
base.extend_from_slice(&ext);
base
}
}
fn volume_label(name: &[u8; 11]) -> Vec<u8> {
let mut end = name.len();
while end > 0 && (name[end - 1] == b' ' || name[end - 1] == 0) {
end -= 1;
}
let mut out = name[..end].to_vec();
if out.first() == Some(&NAME_LEADING_E5) {
out[0] = 0xE5;
}
out
}
fn decode_utf16(units: &[u16]) -> (Vec<u8>, bool) {
let mut ill_formed = false;
let text: String = char::decode_utf16(units.iter().copied())
.map(|r| {
r.unwrap_or_else(|_| {
ill_formed = true;
char::REPLACEMENT_CHARACTER
})
})
.collect();
(text.into_bytes(), ill_formed)
}
fn check_times(
entry: &DirEntry,
index: u32,
at: Location,
deviations: &mut OnDeviation<'_>,
) -> Result<(), ReadError> {
let optional = [
(
"creation time",
DosTimestamp {
date: entry.create_date,
time: entry.create_time,
tenth: entry.create_time_tenth,
},
),
(
"access time",
DosTimestamp {
date: entry.access_date,
time: 0,
tenth: 0,
},
),
];
for (field, stamp) in optional {
if stamp != DosTimestamp::default() && !stamp.is_well_formed() {
deviations.record(at, ReadError::MalformedTimestamp { index, field })?;
}
}
let write = DosTimestamp {
date: entry.write_date,
time: entry.write_time,
tenth: 0,
};
if !write.is_well_formed() {
deviations.record(
at,
ReadError::MalformedTimestamp {
index,
field: "modification time",
},
)?;
}
Ok(())
}
fn is_volume_label(attributes: DirAttributes) -> bool {
attributes.contains(DirAttributes::VOLUME_ID)
&& !attributes.is_long_name()
&& !attributes.contains(DirAttributes::DIRECTORY)
}
fn lookup_keys(entry: &Entry) -> Vec<Vec<u8>> {
let fold = |name: &[u8]| {
super::name::folded(name).map_or_else(|| name.to_ascii_lowercase(), String::into_bytes)
};
let name = fold(&entry.name);
let short = fold(&entry.short_name);
if short == name {
vec![name]
} else {
vec![name, short]
}
}
fn first_cluster(entry: &DirEntry, fat_type: FatType) -> u32 {
match fat_type {
FatType::Fat32 => {
(u32::from(entry.first_cluster_hi) << 16) | u32::from(entry.first_cluster_lo)
}
FatType::Fat12 | FatType::Fat16 => u32::from(entry.first_cluster_lo),
}
}
fn node_of(entry: &DirEntry, fat_type: FatType) -> Node {
let first = first_cluster(entry, fat_type);
Node {
storage: if first < 2 {
Storage::None
} else {
Storage::Chain(first)
},
attributes: entry.attributes,
size: entry.size,
times: Some(Times {
create: Some(DosTimestamp {
date: entry.create_date,
time: entry.create_time,
tenth: entry.create_time_tenth,
})
.filter(|stamp| *stamp != DosTimestamp::default())
.map(DosTimestamp::decode),
access: (entry.access_date != 0).then(|| {
DosTimestamp {
date: entry.access_date,
time: 0,
tenth: 0,
}
.decode()
}),
modify: DosTimestamp {
date: entry.write_date,
time: entry.write_time,
tenth: 0,
}
.decode(),
}),
}
}
impl<R: Read + Seek> FsTree for Reader<R> {
type Node = Node;
fn family(&self) -> Family {
Family::Fat
}
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 = node_kind(&entry.node);
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(DirAttributes::READ_ONLY),
node.times.map(|t| (t.access, t.modify, t.create)),
))
}
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::Fat,
detail: "a FAT volume holds no symbolic links".to_string(),
})
}
fn find(&mut self, path: &[u8]) -> Result<Child<Node>, TreeError> {
let node = self.lookup(path).map_err(|e| match e {
ReadError::NotFound { .. } | ReadError::NotADirectory { .. } => TreeError::NotFound {
family: Family::Fat,
path: path.to_vec(),
},
other => TreeError::from(other),
})?;
Ok(Child::new(
crate::tree::last_name(path),
node_kind(&node),
node,
))
}
fn list(&mut self, dir: &Node) -> Result<Vec<Child<Node>>, TreeError> {
if !dir.is_dir() {
return Err(crate::tree::not_a_directory(Family::Fat));
}
let entries = self.read_dir(dir)?.into_iter().map(|e| (e.name, e.node));
Ok(crate::tree::listed(Family::Fat, entries)?
.into_iter()
.map(|(name, node)| Child::new(name, node_kind(&node), node))
.collect())
}
fn usage(&mut self) -> Result<Usage, TreeError> {
let census = self.census(None);
if let Some(e) = census.failed {
return Err(e.into());
}
Ok(Usage::new(
u64::from(self.layout.bytes_per_cluster()),
u64::from(self.layout.clusters),
u64::from(census.free),
))
}
}
fn node_kind(node: &Node) -> NodeKind {
if node.is_dir() {
NodeKind::Directory
} else {
NodeKind::File {
size: u64::from(node.size),
}
}
}
type WalkFail<E> = crate::tree::WalkFail<ReadError, E>;
impl<E> From<ReadError> for WalkFail<E> {
fn from(err: ReadError) -> Self {
WalkFail::Read(err)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::fat::{
BootCode, ClusterSize, DiskGeometry, FatTypeRequest, FormatOptions, Image, MEDIA_REMOVABLE,
PlanRequest, ReservedSectors, VolumeLabel, format,
};
use crate::path::canonical_parts;
use crate::source::{Metadata, TreeBuilder};
use std::io::Cursor;
const TIME: Timestamp = Timestamp::from_secs(1_426_325_212);
fn options() -> FormatOptions {
FormatOptions::new(0x1234_abcd, TIME)
}
fn tree() -> TreeBuilder {
let m = |mode| Metadata::new(mode, TIME);
TreeBuilder::new()
.directory(b"/EFI".to_vec(), m(0o755))
.directory(b"/EFI/BOOT".to_vec(), m(0o755))
.file(
b"/EFI/BOOT/BOOTX64.EFI".to_vec(),
b"MZ\x90\x00".to_vec(),
m(0o644),
)
.file(b"/readme.txt".to_vec(), b"hello\n".to_vec(), m(0o644))
.file(
b"/a-long-file-name.text".to_vec(),
vec![b'x'; 5000],
m(0o644),
)
.file(
b"/a-long-file-name-two.text".to_vec(),
b"two".to_vec(),
m(0o644),
)
.file(b"/empty".to_vec(), Vec::new(), m(0o444))
}
fn image(mib: u64, request: FatTypeRequest) -> Image {
let opts = options()
.label(VolumeLabel::new("FERROSYS").expect("label"))
.plan(PlanRequest::new(0).fat_type(request));
format(tree(), mib << 20, opts).expect("format")
}
fn each_type() -> [(FatType, Image); 3] {
[
(
FatType::Fat12,
image(2, FatTypeRequest::Exactly(FatType::Fat12)),
),
(
FatType::Fat16,
image(64, FatTypeRequest::Exactly(FatType::Fat16)),
),
(
FatType::Fat32,
image(512, FatTypeRequest::Exactly(FatType::Fat32)),
),
]
}
fn reader(image: &Image) -> Reader<Cursor<&[u8]>> {
Reader::open(Cursor::new(image.as_bytes())).expect("open")
}
fn at(layout: &FatLayout, sector: u32) -> usize {
sector as usize * layout.bytes_per_sector as usize
}
#[test]
fn a_table_read_never_reaches_past_the_copy_it_is_in() {
for (_, image) in each_type() {
let r = reader(&image);
let last = r.layout.fat_sectors - 1;
assert_eq!(
r.table_window_sectors(last),
1,
"the copy's last sector has no next sector of its own"
);
assert_eq!(r.table_window_sectors(last.saturating_sub(1)), 2);
assert_eq!(r.table_window_sectors(u32::MAX), 1);
}
}
#[test]
fn the_layout_read_back_is_the_layout_planned() {
for (what, image) in each_type() {
let r = reader(&image);
assert_eq!(r.layout(), image.layout(), "{what}");
assert_eq!(r.fat_type(), what);
}
}
#[test]
fn every_name_the_writer_placed_reads_back() {
for (what, image) in each_type() {
let mut r = reader(&image);
let mut paths: Vec<Vec<u8>> = r
.walk()
.expect("walk")
.into_iter()
.map(|e| e.path)
.collect();
paths.sort();
let expected: Vec<&[u8]> = vec![
b"/EFI",
b"/EFI/BOOT",
b"/EFI/BOOT/BOOTX64.EFI",
b"/a-long-file-name-two.text",
b"/a-long-file-name.text",
b"/empty",
b"/readme.txt",
];
let got: Vec<&[u8]> = paths.iter().map(Vec::as_slice).collect();
assert_eq!(got, expected, "{what}");
}
}
#[test]
fn every_file_reads_back_byte_for_byte() {
for (what, image) in each_type() {
let mut r = reader(&image);
for (path, expected) in [
(&b"/EFI/BOOT/BOOTX64.EFI"[..], b"MZ\x90\x00".to_vec()),
(b"/readme.txt", b"hello\n".to_vec()),
(b"/a-long-file-name.text", vec![b'x'; 5000]),
(b"/a-long-file-name-two.text", b"two".to_vec()),
(b"/empty", Vec::new()),
] {
let node = r.lookup(path).unwrap_or_else(|e| {
panic!("{what}: {} not found: {e}", String::from_utf8_lossy(path))
});
assert_eq!(u64::from(node.size), expected.len() as u64, "{what}");
assert_eq!(
r.read_data(&node).expect("read"),
expected,
"{what}: {}",
String::from_utf8_lossy(path)
);
}
}
}
#[test]
fn a_multi_cluster_file_reads_the_same_whole_as_it_does_in_pieces() {
for (what, image) in each_type() {
let mut r = reader(&image);
let node = r.lookup(b"/a-long-file-name.text").expect("lookup");
let whole = r.read_data(&node).expect("whole");
for chunk in [1usize, 7, 512, 4096] {
let mut pieces = Vec::new();
let mut buf = vec![0u8; chunk];
let mut offset = 0u64;
loop {
let got = r.read_into(&node, offset, &mut buf).expect("piece");
if got == 0 {
break;
}
pieces.extend_from_slice(&buf[..got]);
offset += got as u64;
}
assert_eq!(pieces, whole, "{what}: in {chunk}-byte pieces");
}
let mut buf = [0u8; 16];
for start in (0..whole.len()).step_by(997).rev() {
let got = r
.read_into(&node, start as u64, &mut buf)
.expect("backwards");
assert_eq!(&buf[..got], &whole[start..start + got], "{what}");
}
}
}
#[test]
fn a_short_name_is_kept_beside_the_name_and_says_whether_a_long_one_was_used() {
for (what, image) in each_type() {
let mut r = reader(&image);
let root = r.root();
let entries = r.read_dir(&root).expect("read the root");
let by_name = |n: &[u8]| {
entries
.iter()
.find(|e| e.name == n)
.unwrap_or_else(|| panic!("{what}: {} absent", String::from_utf8_lossy(n)))
};
let readme = by_name(b"readme.txt");
assert!(readme.has_long_name, "{what}");
assert_eq!(readme.short_name, b"README.TXT", "{what}");
let one = by_name(b"a-long-file-name.text");
let two = by_name(b"a-long-file-name-two.text");
assert_ne!(one.short_name, two.short_name, "{what}");
let efi = r.lookup(b"/EFI/BOOT").expect("lookup");
let boot = r.read_dir(&efi).expect("read");
let payload = boot
.iter()
.find(|e| e.name == b"BOOTX64.EFI")
.expect("entry");
assert!(
!payload.has_long_name,
"{what}: a name that is its own short name took a long-name run"
);
assert_eq!(payload.short_name, b"BOOTX64.EFI");
}
}
#[test]
fn a_name_is_found_by_its_short_alias_as_well_as_by_its_long_name() {
let m = |mode| Metadata::new(mode, TIME);
let source = TreeBuilder::new()
.directory(b"/Long directory name".to_vec(), m(0o755))
.file(
b"/Long directory name/Long filename.txt".to_vec(),
b"alias contents".to_vec(),
m(0o644),
);
for request in [FatType::Fat12, FatType::Fat16, FatType::Fat32] {
let mib = match request {
FatType::Fat12 => 2,
FatType::Fat16 => 64,
FatType::Fat32 => 512,
};
let opts =
options().plan(PlanRequest::new(0).fat_type(FatTypeRequest::Exactly(request)));
let image = format(source.clone(), mib << 20, opts).expect("format");
let mut r = reader(&image);
let root = r.root();
let dir = r
.read_dir(&root)
.expect("read the root")
.into_iter()
.find(|e| e.name == b"Long directory name")
.expect("the directory");
let inner = r.read_dir(&dir.node).expect("read the directory");
let file = inner
.iter()
.find(|e| e.name == b"Long filename.txt")
.expect("the file");
assert!(dir.has_long_name && file.has_long_name, "{request:?}");
assert_ne!(file.short_name, file.name, "{request:?}");
let by_long = r
.lookup(b"/Long directory name/Long filename.txt")
.expect("the long names resolve");
let alias = |bytes: &[u8]| String::from_utf8(bytes.to_vec()).expect("ASCII");
let (dir_alias, file_alias) = (alias(&dir.short_name), alias(&file.short_name));
for path in [
format!("/{dir_alias}/{file_alias}"),
format!(
"/{}/{}",
dir_alias.to_lowercase(),
file_alias.to_lowercase()
),
format!("/Long directory name/{file_alias}"),
format!("/{dir_alias}/Long filename.txt"),
] {
let found = r
.lookup(path.as_bytes())
.unwrap_or_else(|e| panic!("{request:?}: {path} does not resolve: {e}"));
assert_eq!(found, by_long, "{request:?}: {path}");
assert_eq!(
r.read_data(&found).expect("read"),
b"alias contents",
"{request:?}: {path}"
);
}
}
}
#[test]
fn the_case_flags_are_honoured_on_reading_and_never_written() {
for (what, image) in each_type() {
let mut r = reader(&image);
let root = r.root();
r.for_each_slot::<ReadError>(&root, |_, slot| {
assert_eq!(
slot.entry.case_flags, 0,
"{what}: the writer set a reserved case flag"
);
Ok(ControlFlow::Continue(()))
})
.expect("raw");
}
assert_eq!(render_short(b"README TXT", 0), b"README.TXT");
assert_eq!(render_short(b"README TXT", NT_LOWER_BASE), b"readme.TXT");
assert_eq!(render_short(b"README TXT", NT_LOWER_EXT), b"README.txt");
assert_eq!(
render_short(b"README TXT", NT_LOWER_BASE | NT_LOWER_EXT),
b"readme.txt"
);
assert_eq!(
render_short(b"CAF\xE9 TXT", NT_LOWER_BASE),
b"caf\xE9.TXT".to_vec(),
"the flag names the base alone, and the byte above ASCII has no case"
);
}
#[test]
fn a_name_with_no_extension_keeps_no_dot() {
assert_eq!(render_short(b"EMPTY ", 0), b"EMPTY");
assert_eq!(render_short(b"A B ", 0), b"A.B");
assert_eq!(render_short(b"\x05BC ", 0), b"\xE5BC".to_vec());
}
#[test]
fn the_volume_label_comes_from_the_root_entry() {
for (what, image) in each_type() {
let mut r = reader(&image);
assert_eq!(
r.volume_label().expect("label"),
Some(b"FERROSYS".to_vec()),
"{what}"
);
let root = r.root();
let names: Vec<Vec<u8>> = r
.read_dir(&root)
.expect("read")
.into_iter()
.map(|e| e.name)
.collect();
assert!(!names.contains(&b"FERROSYS".to_vec()), "{what}");
}
}
#[test]
fn an_access_date_of_zero_is_a_date_not_kept() {
use crate::tree::FsTree;
let (_, image) = each_type().into_iter().next().expect("a type");
let mut bytes = image.as_bytes().to_vec();
let at = bytes
.windows(11)
.position(|w| w == b"BOOTX64 EFI")
.expect("the entry");
bytes[at + 18..at + 20].fill(0);
let mut r = Reader::open(Cursor::new(&bytes[..])).expect("open");
let node = r.lookup(b"/EFI/BOOT/BOOTX64.EFI").expect("the file");
let times = node.times.expect("an entry's times");
assert_eq!(times.access, None);
let stat = r.stat(&node, &Synthesis::new()).expect("its attributes");
assert!(
stat.synthesized
.contains(&crate::fidelity::Property::AccessTime)
);
assert_eq!(stat.meta.atime, stat.meta.mtime);
}
#[test]
fn a_label_entry_of_spaces_is_no_label_and_one_led_by_a_space_is_reported() {
for (what, image) in each_type() {
let bytes = image.as_bytes().to_vec();
let at = bytes
.windows(12)
.position(|w| w == b"FERROSYS \x08")
.expect("the label entry");
let mut led = bytes.clone();
led[at..at + 11].copy_from_slice(b" FERROSYS ");
let mut r = Reader::open_with(
Cursor::new(&led[..]),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
assert!(
r.scan()
.anomalies()
.iter()
.any(|a| a.detail.contains("beginning with a space")),
"{what}"
);
let mut blank = bytes;
blank[at..at + 11].fill(b' ');
let mut r = Reader::open_with(
Cursor::new(&blank[..]),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
assert_eq!(r.volume_label().expect("a label read"), None, "{what}");
}
}
#[test]
fn a_strict_scan_of_a_volume_this_crate_wrote_is_clean() {
for (what, image) in each_type() {
let mut r = reader(&image);
let report = r.scan();
assert!(report.is_clean(), "{what}: {:#?}", report.anomalies());
assert!(!report.has_fatal(ReadPolicy::Strict), "{what}");
r.verify_tables()
.unwrap_or_else(|e| panic!("{what}: the tables disagree: {e}"));
}
}
#[test]
fn a_strict_read_accepts_every_volume_the_writer_produces_at_every_option() {
type Variant = (&'static str, Box<dyn Fn(FormatOptions) -> FormatOptions>);
let long_code = vec![0x90u8; BootCode::MAX_BYTES_FAT32];
let mut variants: Vec<Variant> = vec![
("default", Box::new(|o: FormatOptions| o)),
(
"unlabelled",
Box::new(|mut o: FormatOptions| {
o.label = None;
o
}),
),
(
"oem name",
Box::new(|mut o: FormatOptions| {
o.oem_name = *b"MSWIN4.1";
o
}),
),
(
"hidden sectors",
Box::new(|mut o: FormatOptions| {
o.hidden_sectors = 2048;
o
}),
),
(
"disk geometry",
Box::new(|o: FormatOptions| {
let most = std::num::NonZeroU16::MAX;
o.disk_geometry(DiskGeometry::Exactly {
sectors_per_track: most,
heads: most,
})
}),
),
(
"volume id",
Box::new(|mut o: FormatOptions| {
o.volume_id = 0;
o
}),
),
(
"earliest time",
Box::new(|mut o: FormatOptions| {
o.time = Timestamp::from_secs(DosTimestamp::SECS_MIN);
o
}),
),
(
"latest time",
Box::new(|mut o: FormatOptions| {
o.time = Timestamp::from_secs(DosTimestamp::SECS_MAX);
o
}),
),
(
"boot code",
Box::new(move |o: FormatOptions| {
o.boot_code(BootCode::new(&long_code).expect("boot code"))
}),
),
];
let FormatOptions {
label: _,
oem_name: _,
hidden_sectors: _,
disk_geometry: _,
volume_id: _,
time: _,
media: _,
boot_code: _,
plan: _,
accepted_loss: _,
synthesis: _,
} = options();
for media in (0xF8u8..=0xFF).chain([MEDIA_REMOVABLE]) {
variants.push((
"media",
Box::new(move |mut o: FormatOptions| {
o.media = media;
o
}),
));
}
for (what, mib) in [
(FatType::Fat12, 2u64),
(FatType::Fat16, 64),
(FatType::Fat32, 512),
] {
for (name, vary) in &variants {
let base = options()
.label(VolumeLabel::new("FERROSYS").expect("label"))
.plan(PlanRequest::new(0).fat_type(FatTypeRequest::Exactly(what)));
let image = format(tree(), mib << 20, vary(base))
.unwrap_or_else(|e| panic!("{what} / {name}: format: {e}"));
let mut r = Reader::open(Cursor::new(image.as_bytes()))
.unwrap_or_else(|e| panic!("{what} / {name}: a strict open: {e}"));
assert_eq!(r.layout(), image.layout(), "{what} / {name}");
let report = r.scan();
assert!(
report.is_clean(),
"{what} / {name}: {:#?}",
report.anomalies()
);
}
}
}
#[test]
fn an_undersized_fat32_is_remarked_on_and_not_refused() {
let opts = options().plan(
PlanRequest::new(0)
.cluster_size(ClusterSize::Sectors(1))
.reserved_sectors(ReservedSectors::Count(32))
.fat_type(FatTypeRequest::UndersizedFat32),
);
let image = format(TreeBuilder::new(), 8 << 20, opts).expect("format");
let mut r = Reader::open(Cursor::new(image.as_bytes())).expect("a strict open");
assert_eq!(r.fat_type(), FatType::Fat32);
assert!(r.layout().clusters < crate::fat::MIN_CLUSTERS_FAT32);
let report = r.scan();
assert!(report.is_clean(), "{:#?}", report.anomalies());
}
#[test]
fn the_reader_opens_exactly_what_detection_claims() {
for (_, image) in each_type() {
let bytes = image.as_bytes();
assert!(matches!(
crate::detect(Cursor::new(bytes)),
Ok(crate::Filesystem::Fat(_))
));
assert!(Reader::open(Cursor::new(bytes)).is_ok());
}
let mut mbr = vec![0u8; 1 << 20];
mbr[510] = 0x55;
mbr[511] = 0xAA;
mbr[0..3].copy_from_slice(&[0xEB, 0x3C, 0x90]);
assert!(crate::detect(Cursor::new(&mbr)).is_err());
assert!(matches!(
Reader::open(Cursor::new(&mbr)),
Err(ReadError::BadBootSector { .. })
));
}
#[test]
fn a_volume_inside_a_larger_image_reads_at_its_own_offset() {
const BASE: u64 = 1 << 20;
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut disk = vec![0u8; BASE as usize];
disk.extend_from_slice(image.as_bytes());
assert!(Reader::open(Cursor::new(&disk)).is_err());
let mut r = Reader::open_with(Cursor::new(&disk), &OpenOptions::new().base(BASE))
.expect("open at the partition's start");
assert_eq!(r.layout(), image.layout());
assert_eq!(r.walk().expect("walk").len(), 7);
}
#[test]
fn a_volume_longer_than_its_region_is_refused_and_one_inside_it_opens() {
const BASE: u64 = 1 << 20;
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let len = image.as_bytes().len() as u64;
let mut disk = vec![0u8; BASE as usize];
disk.extend_from_slice(image.as_bytes());
disk.extend(vec![0xee; 1 << 20]);
for policy in [ReadPolicy::Strict, ReadPolicy::Lenient] {
assert!(matches!(
Reader::open_with(
Cursor::new(&disk),
&OpenOptions::new().base(BASE).len(len - 1).policy(policy)
),
Err(ReadError::BadBootSector {
field: "BPB_TotSec32",
..
})
));
}
for options in [
OpenOptions::new().base(BASE).len(len),
OpenOptions::new().base(BASE),
] {
let mut r = Reader::open_with(Cursor::new(&disk), &options).expect("open");
assert_eq!(r.walk().expect("walk").len(), 7);
assert!(r.scan().is_clean());
}
}
#[test]
fn a_lookup_finds_a_name_however_its_letters_are_cased() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut r = reader(&image);
for path in [
&b"/EFI/BOOT/BOOTX64.EFI"[..],
b"/efi/boot/bootx64.efi",
b"/EFI/boot/BootX64.efi",
b"//EFI//BOOT//BOOTX64.EFI",
b"/./EFI/BOOT/BOOTX64.EFI",
b"/EFI/BOOT/BOOTX64.EFI/",
b"EFI/BOOT/BOOTX64.EFI",
] {
let node = r
.lookup(path)
.unwrap_or_else(|e| panic!("{}: {e}", String::from_utf8_lossy(path)));
assert_eq!(node.size, 4);
assert_eq!(
crate::path::canonical_key(path).to_ascii_uppercase(),
b"EFI/BOOT/BOOTX64.EFI",
"{}: one path to a model as well as to a lookup",
String::from_utf8_lossy(path)
);
}
assert!(matches!(
r.lookup(b"/EFI/BOOT/NOPE"),
Err(ReadError::NotFound { .. })
));
assert!(matches!(
r.lookup(b"/readme.txt/deeper"),
Err(ReadError::NotADirectory { .. })
));
}
#[test]
fn a_parent_component_ascends_though_no_entry_of_that_name_is_ever_handed_back() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut r = reader(&image);
let boot = r.lookup(b"/EFI/BOOT").expect("lookup");
let listed = r.read_dir(&boot).expect("read the subdirectory");
assert!(
!listed
.iter()
.any(|e| is_hostile_component(&e.name) || is_hostile_component(&e.short_name)),
"a name no path component may carry reached a caller: {:?}",
listed.iter().map(|e| &e.name).collect::<Vec<_>>()
);
assert_eq!(listed.len(), 1);
let want = r.lookup(b"/EFI/BOOT/BOOTX64.EFI").expect("lookup");
assert_eq!(
r.lookup(b"/EFI/BOOT/../BOOT/BOOTX64.EFI")
.map(|node| node.storage),
Ok(want.storage)
);
assert_eq!(
r.lookup(b"/EFI/..").map(|n| n.storage),
Ok(r.root().storage)
);
}
#[test]
fn a_directory_holds_no_bytes_and_yields_none() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut r = reader(&image);
let dir = r.lookup(b"/EFI").expect("lookup");
assert!(dir.is_dir());
assert_eq!(r.read_data(&dir).expect("read"), Vec::<u8>::new());
let mut buf = [0u8; 32];
assert_eq!(r.read_into(&dir, 0, &mut buf).expect("read"), 0);
}
#[test]
fn the_read_limit_refuses_rather_than_shortening() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut r = Reader::open_with(
Cursor::new(image.as_bytes()),
&OpenOptions::new().limits(Limits::new().max_file_bytes(1024)),
)
.expect("open");
let node = r.lookup(b"/a-long-file-name.text").expect("lookup");
assert!(matches!(
r.read_data(&node),
Err(ReadError::FileTooLarge {
size: 5000,
limit: 1024
})
));
assert!(matches!(
r.read_data_to(&node, std::io::sink()),
Err(ReadError::FileTooLarge {
size: 5000,
limit: 1024
})
));
let mut buf = [0u8; 64];
assert_eq!(r.read_into(&node, 0, &mut buf).expect("read"), 64);
}
#[test]
fn a_time_the_encoding_does_not_define_is_named_where_the_entry_is_read() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let entry = entry_of(&image, b"EMPTY ");
let mut bytes = image.as_bytes().to_vec();
let odd = ((2035u16 - 1980) << 9) | (2 << 5) | 31;
bytes[entry + 24..entry + 26].copy_from_slice(&odd.to_le_bytes());
let err = Reader::open(Cursor::new(bytes.as_slice()))
.expect("open")
.walk()
.expect_err("a strict read refuses it");
assert!(
matches!(
err,
ReadError::MalformedTimestamp {
field: "modification time",
..
}
),
"{err}"
);
let mut bytes = image.as_bytes().to_vec();
bytes[entry + 13] = 0;
bytes[entry + 14..entry + 18].copy_from_slice(&0u32.to_le_bytes());
Reader::open(Cursor::new(bytes.as_slice()))
.expect("open")
.walk()
.expect("a field the format calls optional and absent stops no read");
let mut bytes = image.as_bytes().to_vec();
bytes[entry + 16..entry + 18].copy_from_slice(&0u16.to_le_bytes());
let err = Reader::open(Cursor::new(bytes.as_slice()))
.expect("open")
.walk()
.expect_err("a strict read refuses it");
assert!(
matches!(
err,
ReadError::MalformedTimestamp {
field: "creation time",
..
}
),
"{err}"
);
}
#[test]
fn a_creation_field_left_zero_reads_as_no_birth_time() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let entry = entry_of(&image, b"EMPTY ");
let birth = |bytes: &[u8]| {
let mut r = Reader::open(Cursor::new(bytes)).expect("open");
let node = r.lookup(b"/empty").expect("the file");
FsTree::stat(&mut r, &node, &Synthesis::default())
.expect("stat")
.meta
.btime
};
assert!(birth(image.as_bytes()).is_some());
let mut bytes = image.as_bytes().to_vec();
bytes[entry + 13] = 0;
bytes[entry + 14..entry + 18].copy_from_slice(&0u32.to_le_bytes());
assert_eq!(birth(&bytes), None);
let mut r = Reader::open(Cursor::new(image.as_bytes())).expect("open");
let root = r.root();
let stat = FsTree::stat(&mut r, &root, &Synthesis::default()).expect("stat");
assert_eq!(stat.meta.btime, None);
}
#[test]
fn a_directory_two_entries_lead_to_is_refused_strictly_and_passed_over_leniently() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let efi = match reader(&image).lookup(b"/EFI").expect("lookup").storage {
Storage::Chain(start) => start,
_ => panic!("the fixture's directory owns no chain"),
};
let entry = entry_of(&image, b"BOOT ");
let mut bytes = image.as_bytes().to_vec();
bytes[entry + 26..entry + 28].copy_from_slice(&((efi & 0xffff) as u16).to_le_bytes());
bytes[entry + 20..entry + 22].copy_from_slice(&((efi >> 16) as u16).to_le_bytes());
let err = Reader::open(Cursor::new(bytes.as_slice()))
.expect("open")
.walk()
.expect_err("a strict read refuses it");
assert!(
matches!(err, ReadError::RepeatedDirectory { cluster } if cluster == efi),
"{err:?}"
);
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let paths: Vec<Vec<u8>> = r
.walk()
.expect("a lenient read passes it over")
.into_iter()
.map(|e| e.path)
.collect();
assert!(paths.contains(&b"/EFI/BOOT".to_vec()));
assert!(
!paths.iter().any(|p| p.starts_with(b"/EFI/BOOT/")),
"the repeat is not descended into: {paths:?}"
);
}
fn cluster_of(image: &Image, path: &[u8]) -> u32 {
match reader(image).lookup(path).expect("lookup").storage {
Storage::Chain(start) => start,
_ => panic!("{} owns no chain", String::from_utf8_lossy(path)),
}
}
fn point_at(bytes: &mut [u8], off: usize, cluster: u32) {
bytes[off + 20..off + 22].copy_from_slice(&((cluster >> 16) as u16).to_le_bytes());
bytes[off + 26..off + 28].copy_from_slice(&((cluster & 0xffff) as u16).to_le_bytes());
}
fn walked_and_scanned(bytes: &[u8]) -> (Result<Vec<WalkEntry>, ReadError>, ScanReport) {
let strict = Reader::open(Cursor::new(bytes))
.expect("a strict open")
.walk();
let report = Reader::open_with(
Cursor::new(bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open")
.scan();
(strict, report)
}
#[test]
fn a_dot_entry_naming_another_cluster_is_found_and_refused_strictly() {
for (fat_type, image) in each_type() {
let efi = cluster_of(&image, b"/EFI");
let boot = cluster_of(&image, b"/EFI/BOOT");
let layout = *image.layout();
let at_boot = at(
&layout,
layout.cluster_start_sector(boot).expect("a cluster"),
);
for (slot, name, expected) in [(0usize, ".", boot), (1, "..", efi)] {
let mut bytes = image.as_bytes().to_vec();
point_at(&mut bytes, at_boot + slot * DIR_ENTRY_SIZE, expected + 1);
let (strict, report) = walked_and_scanned(&bytes);
let wrong = ReadError::DotEntryTarget {
path: b"/EFI/BOOT".to_vec(),
name,
found: expected + 1,
expected,
};
assert_eq!(strict.expect_err("a strict walk refuses it"), wrong);
assert!(
report
.anomalies()
.iter()
.any(|a| a.detail == wrong.to_string()
&& a.severity == Severity::Integrity),
"{fat_type:?} {name}: {:?}",
report.anomalies()
);
}
}
}
#[test]
fn the_high_half_of_a_dot_entrys_cluster_counts_on_fat32_alone() {
for (fat_type, image) in each_type() {
let boot = cluster_of(&image, b"/EFI/BOOT");
let layout = *image.layout();
let off = at(
&layout,
layout.cluster_start_sector(boot).expect("a cluster"),
) + DIR_ENTRY_SIZE
+ 20;
let mut bytes = image.as_bytes().to_vec();
bytes[off..off + 2].copy_from_slice(&1u16.to_le_bytes());
let (strict, report) = walked_and_scanned(&bytes);
if fat_type == FatType::Fat32 {
assert!(
matches!(
strict,
Err(ReadError::DotEntryTarget { name: "..", found, .. }) if found >> 16 == 1
),
"{strict:?}"
);
} else {
assert!(strict.is_ok(), "{fat_type:?}: {strict:?}");
assert!(report.is_clean(), "{fat_type:?}: {:?}", report.anomalies());
}
}
}
#[test]
fn a_dot_entry_missing_or_out_of_place_is_found_and_never_an_entry() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let efi = cluster_of(&image, b"/EFI");
let boot = cluster_of(&image, b"/EFI/BOOT");
let at_efi = at(
&layout,
layout.cluster_start_sector(efi).expect("a cluster"),
);
let at_boot = at(
&layout,
layout.cluster_start_sector(boot).expect("a cluster"),
);
let at_root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
let sound: Vec<Vec<u8>> = reader(&image)
.walk()
.expect("walk")
.into_iter()
.map(|e| e.path)
.collect();
let free = |bytes: &[u8], dir: usize| {
(0..)
.map(|n| dir + n * DIR_ENTRY_SIZE)
.find(|&off| bytes[off] == 0)
.expect("a free slot")
};
type Case<'a> = (&'a str, Box<dyn Fn(&mut Vec<u8>) + 'a>, &'a str);
let cases: [Case<'_>; 5] = [
(
"a `..` in slot 3 of /EFI",
Box::new(|b: &mut Vec<u8>| {
let to = free(b, at_efi);
let dotdot = b[at_efi + DIR_ENTRY_SIZE..at_efi + 2 * DIR_ENTRY_SIZE].to_vec();
b[to..to + DIR_ENTRY_SIZE].copy_from_slice(&dotdot);
}),
"/EFI: entry 3 is a `..` entry, where the format puts none",
),
(
"a `..` in the root",
Box::new(|b: &mut Vec<u8>| {
let to = free(b, at_root);
let dotdot = b[at_efi + DIR_ENTRY_SIZE..at_efi + 2 * DIR_ENTRY_SIZE].to_vec();
b[to..to + DIR_ENTRY_SIZE].copy_from_slice(&dotdot);
}),
"a `..` entry, where the format puts none",
),
(
"a `..` without the directory attribute",
Box::new(|b: &mut Vec<u8>| b[at_boot + DIR_ENTRY_SIZE + 11] = 0x20),
"/EFI/BOOT: the `..` entry does not carry the directory attribute",
),
(
"a `.` deleted",
Box::new(|b: &mut Vec<u8>| b[at_boot] = 0xE5),
"/EFI/BOOT: entry 0 is not the `.` entry the format puts there",
),
(
"a `..` named otherwise",
Box::new(|b: &mut Vec<u8>| b[at_boot + DIR_ENTRY_SIZE + 1] = b'X'),
"/EFI/BOOT: entry 1 is not the `..` entry the format puts there",
),
];
for (what, damage, detail) in cases {
let mut bytes = image.as_bytes().to_vec();
damage(&mut bytes);
let (strict, report) = walked_and_scanned(&bytes);
assert!(
matches!(strict, Err(ReadError::BadDotEntry { .. })),
"{what}: {strict:?}"
);
let found: Vec<&Anomaly> = report
.anomalies()
.iter()
.filter(|a| a.detail.ends_with(detail))
.collect();
assert_eq!(found.len(), 1, "{what}: {:?}", report.anomalies());
assert_eq!(found[0].severity, Severity::Conformance, "{what}");
let mut lenient = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let paths: Vec<Vec<u8>> = lenient
.walk()
.expect("a lenient walk")
.into_iter()
.map(|e| e.path)
.filter(|p| !p.ends_with(b"/.X"))
.collect();
assert_eq!(paths, sound, "{what}");
}
}
fn read_three_ways(bytes: &[u8]) -> (bool, Vec<Vec<u8>>, ScanReport) {
let refused = Reader::open(Cursor::new(bytes))
.expect("a strict open")
.walk()
.is_err();
let mut lenient = Reader::open_with(
Cursor::new(bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open");
let paths = lenient
.walk()
.expect("a lenient walk")
.into_iter()
.map(|e| e.path)
.collect();
(refused, paths, lenient.scan())
}
#[test]
fn a_character_the_format_reserves_in_a_name_is_named_and_the_name_handed_back() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let bootx64 = entry_of(&image, b"BOOTX64 EFI");
let readme = entry_of(&image, b"README TXT");
let unit = readme - DIR_ENTRY_SIZE + 9;
assert_eq!(
&image.as_bytes()[unit..unit + 2],
b"m\0",
"the fixture's long name"
);
type Case<'a> = (&'a str, usize, u8, &'a [u8], &'a str, u32);
let cases: [Case<'_>; 3] = [
(
"a short `+`",
bootx64 + 1,
b'+',
b"/EFI/BOOT/B+OTX64.EFI",
"short",
0x2b,
),
("a long `:`", unit, b':', b"/read:e.txt", "long", 0x3a),
(
"a leading space",
bootx64,
b' ',
b"/EFI/BOOT/ OOTX64.EFI",
"short",
0x20,
),
];
for (what, at, byte, listed, field, code) in cases {
let mut bytes = image.as_bytes().to_vec();
bytes[at] = byte;
let (refused, paths, report) = read_three_ways(&bytes);
assert!(refused, "{what}: a strict walk refuses it");
assert!(paths.contains(&listed.to_vec()), "{what}: {paths:?}");
let named: Vec<&Anomaly> = report
.anomalies()
.iter()
.filter(|a| a.detail.contains(&format!("the {field} name at entry")))
.collect();
assert_eq!(named.len(), 1, "{what}: {:?}", report.anomalies());
assert_eq!(named[0].severity, Severity::Conformance, "{what}");
assert!(
named[0].detail.contains(&format!("{code:#06x}")),
"{what}: {}",
named[0].detail
);
}
let mut bytes = image.as_bytes().to_vec();
bytes[bootx64] = 0x05;
let (_, _, report) = read_three_ways(&bytes);
assert!(
!report
.anomalies()
.iter()
.any(|a| a.detail.contains("the format reserves")),
"{:?}",
report.anomalies()
);
let (_, _, report) = read_three_ways(image.as_bytes());
assert!(report.is_clean(), "{:?}", report.anomalies());
}
#[test]
fn two_names_one_directory_cannot_tell_apart_are_integrity_damage() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let at_root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
let boot = cluster_of(&image, b"/EFI/BOOT");
let at_boot = at(
&layout,
layout.cluster_start_sector(boot).expect("a cluster"),
);
let bootx64 = entry_of(&image, b"BOOTX64 EFI");
let readme = entry_of(&image, b"README TXT");
let free = |bytes: &[u8], dir: usize| {
(0..)
.map(|n| dir + n * DIR_ENTRY_SIZE)
.find(|&off| bytes[off] == 0)
.expect("a free slot")
};
let copy = |bytes: &mut Vec<u8>, from: std::ops::Range<usize>, to: usize| {
let slots = bytes[from].to_vec();
bytes[to..to + slots.len()].copy_from_slice(&slots);
};
let mut twice = image.as_bytes().to_vec();
let to = free(&twice, at_boot);
copy(&mut twice, bootx64..bootx64 + DIR_ENTRY_SIZE, to);
let mut alias = image.as_bytes().to_vec();
let to = free(&alias, at_root);
copy(&mut alias, readme..readme + DIR_ENTRY_SIZE, to);
let mut cased = image.as_bytes().to_vec();
let to = free(&cased, at_root);
let run = readme - DIR_ENTRY_SIZE;
copy(&mut cased, run..readme + DIR_ENTRY_SIZE, to);
let short = to + DIR_ENTRY_SIZE;
cased[short..short + 11].copy_from_slice(b"README~2TXT");
let checksum = DirEntry::read_from(&cased[short..short + DIR_ENTRY_SIZE])
.expect("an entry")
.lfn_checksum();
cased[to + 13] = checksum;
cased[to + 1] = b'R';
for (what, bytes, path, entries) in [
(
"one short name twice",
twice,
&b"/EFI/BOOT/BOOTX64.EFI"[..],
2,
),
("a long name and a short one", alias, b"/readme.txt", 2),
("two long names", cased, b"/readme.txt", 2),
] {
let (refused, paths, report) = read_three_ways(&bytes);
assert!(refused, "{what}: a strict walk refuses it");
let leaf = *crate::path::canonical_parts(path).last().expect("a name");
assert_eq!(
paths
.iter()
.filter(|p| {
crate::path::canonical_parts(p)
.last()
.is_some_and(|n| n.eq_ignore_ascii_case(leaf))
})
.count(),
entries,
"{what}: a lenient walk lists both: {paths:?}"
);
let found: Vec<&Anomaly> = report
.anomalies()
.iter()
.filter(|a| a.detail.contains("once case is folded"))
.collect();
assert_eq!(found.len(), 1, "{what}: {:?}", report.anomalies());
assert_eq!(found[0].severity, Severity::Integrity, "{what}");
}
}
fn findings_naming(bytes: &[u8], detail: &str) -> Vec<Anomaly> {
Reader::open_with(
Cursor::new(bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open")
.scan()
.anomalies()
.iter()
.filter(|a| a.detail.contains(detail))
.cloned()
.collect()
}
#[test]
fn a_directory_entry_recording_a_length_is_remarked_on() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let efi = entry_of(&image, b"EFI ");
let mut bytes = image.as_bytes().to_vec();
bytes[efi + 28..efi + 32].copy_from_slice(&512u32.to_le_bytes());
let found = findings_naming(&bytes, "where a directory records none");
assert_eq!(found.len(), 1, "{found:?}");
assert_eq!(found[0].severity, Severity::Cosmetic);
assert_eq!(
Reader::open(Cursor::new(bytes.as_slice()))
.expect("open")
.walk()
.expect("a strict walk")
.len(),
7
);
}
#[test]
fn a_label_is_one_entry_in_the_root_and_nothing_else_is_one() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let at_root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
let efi = cluster_of(&image, b"/EFI");
let at_efi = at(
&layout,
layout.cluster_start_sector(efi).expect("a cluster"),
);
let label = entry_of(&image, b"FERROSYS ");
let free = |bytes: &[u8], dir: usize| {
(0..)
.map(|n| dir + n * DIR_ENTRY_SIZE)
.find(|&off| bytes[off] == 0)
.expect("a free slot")
};
let label_of = |bytes: &[u8]| {
Reader::open_with(
Cursor::new(bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open")
.volume_label()
.expect("the label")
};
let mut second = image.as_bytes().to_vec();
let to = free(&second, at_root);
let mut entry = second[label..label + DIR_ENTRY_SIZE].to_vec();
entry[..11].copy_from_slice(b"SECOND ");
second[to..to + DIR_ENTRY_SIZE].copy_from_slice(&entry);
let found = findings_naming(&second, "is a second volume label");
assert_eq!(found.len(), 1, "{found:?}");
assert_eq!(found[0].severity, Severity::Conformance);
assert_eq!(label_of(&second), Some(b"FERROSYS".to_vec()));
let mut misplaced = image.as_bytes().to_vec();
let to = free(&misplaced, at_efi);
let entry = misplaced[label..label + DIR_ENTRY_SIZE].to_vec();
misplaced[to..to + DIR_ENTRY_SIZE].copy_from_slice(&entry);
let found = findings_naming(&misplaced, "a volume label entry sits at entry");
assert_eq!(found.len(), 1, "{found:?}");
assert_eq!(found[0].severity, Severity::Conformance);
let mut both = image.as_bytes().to_vec();
both[label + 11] |= 0x10;
let found = findings_naming(&both, "neither a label nor a directory");
assert_eq!(found.len(), 1, "{found:?}");
assert_eq!(found[0].severity, Severity::Conformance);
let walked: Vec<Vec<u8>> = Reader::open_with(
Cursor::new(both.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open")
.walk()
.expect("walk")
.into_iter()
.map(|e| e.path)
.collect();
assert!(
!walked.iter().any(|p| p.starts_with(b"/FERROSYS")),
"{walked:?}"
);
}
#[test]
fn the_free_count_the_information_sector_keeps_is_held_to_the_table() {
let image = image(512, FatTypeRequest::Exactly(FatType::Fat32));
let layout = *image.layout();
let info = at(
&layout,
u32::from(layout.fat32.expect("FAT32").fs_info_sector),
) + 488;
let stated = u32::from_le_bytes(image.as_bytes()[info..info + 4].try_into().expect("four"));
for (value, detail, severity) in [
(stated - 1, "clusters free", Some(Severity::Cosmetic)),
(
layout.clusters + 1,
"more clusters than",
Some(Severity::Conformance),
),
(u32::MAX, "free-cluster hint", None),
] {
let mut bytes = image.as_bytes().to_vec();
bytes[info..info + 4].copy_from_slice(&value.to_le_bytes());
let found = findings_naming(&bytes, detail);
match severity {
Some(severity) => {
assert_eq!(found.len(), 1, "{value}: {found:?}");
assert_eq!(found[0].severity, severity, "{value}");
}
None => assert!(found.is_empty(), "{value}: {found:?}"),
}
}
assert!(findings_naming(image.as_bytes(), "free-cluster hint").is_empty());
}
#[test]
fn a_long_name_ends_at_its_terminator_or_its_padding_and_ill_padding_is_remarked_on() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let run = entry_of(&image, b"README TXT") - DIR_ENTRY_SIZE;
let (nul, pad, last) = (run + 24, run + 28, run + 30);
assert_eq!(&image.as_bytes()[nul..nul + 2], &[0, 0]);
assert_eq!(&image.as_bytes()[last..last + 2], &[0xff, 0xff]);
for (what, at, unit) in [
("padding where the zero is", nul, 0xFFFFu16),
("a character after the zero", pad, u16::from(b'A')),
] {
let mut bytes = image.as_bytes().to_vec();
bytes[at..at + 2].copy_from_slice(&unit.to_le_bytes());
let found = findings_naming(&bytes, "not padded the way the format pads one");
assert_eq!(found.len(), 1, "{what}: {found:?}");
assert_eq!(found[0].severity, Severity::Cosmetic, "{what}");
let names: Vec<Vec<u8>> = Reader::open(Cursor::new(bytes.as_slice()))
.expect("open")
.walk()
.expect("a strict walk")
.into_iter()
.map(|e| e.path)
.collect();
assert!(
names.contains(&b"/readme.txt".to_vec()),
"{what}: {names:?}"
);
}
}
#[test]
fn a_long_name_past_the_format_s_cap_is_named_and_read() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let boot = cluster_of(&image, b"/EFI/BOOT");
let dir = at(
&layout,
layout.cluster_start_sector(boot).expect("a cluster"),
);
let mut bytes = image.as_bytes().to_vec();
let first_free = (0..)
.map(|n| dir + n * DIR_ENTRY_SIZE)
.find(|&off| bytes[off] == 0)
.expect("a free slot");
let mut short = bytes[entry_of(&image, b"BOOTX64 EFI")..][..DIR_ENTRY_SIZE].to_vec();
short[..11].copy_from_slice(b"LONGNAMETXT");
let checksum = DirEntry::read_from(&short)
.expect("an entry")
.lfn_checksum();
for (n, ordinal) in (1..=LFN_MAX_ENTRIES as u8).rev().enumerate() {
let lfn = LfnEntry {
order: ordinal | if n == 0 { LFN_LAST_ENTRY } else { 0 },
name: [u16::from(b'a'); LFN_CHARS_PER_ENTRY],
checksum,
};
let at = first_free + n * DIR_ENTRY_SIZE;
lfn.write_to(&mut bytes[at..at + DIR_ENTRY_SIZE])
.expect("write");
}
let at = first_free + LFN_MAX_ENTRIES * DIR_ENTRY_SIZE;
bytes[at..at + DIR_ENTRY_SIZE].copy_from_slice(&short);
let found = findings_naming(&bytes, "units");
assert!(found.iter().any(|a| a.detail.contains("260")), "{found:?}");
let mut lenient = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let long = format!("/EFI/BOOT/{}", "a".repeat(260));
assert!(lenient.lookup(long.as_bytes()).is_ok(), "the name is read");
assert!(matches!(
Reader::open(Cursor::new(bytes.as_slice()))
.expect("open")
.walk(),
Err(ReadError::LongNameTooLong { units: 260, .. })
));
}
#[test]
fn a_bad_cluster_mark_inside_a_chain_ends_the_read_and_is_named() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let start = cluster_of(&image, b"/a-long-file-name.text");
let mut bytes = image.as_bytes().to_vec();
let bad = table::bad_cluster(FatType::Fat16);
for copy in 0..layout.fats {
let entry =
at(&layout, layout.fat_start_sector(copy).expect("a copy")) + start as usize * 2;
bytes[entry..entry + 2].copy_from_slice(&(bad as u16).to_le_bytes());
}
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
let node = r.lookup(b"/a-long-file-name.text").expect("the name");
assert_eq!(
r.read_data(&node)
.expect_err("the chain runs through a bad cluster"),
ReadError::BadChainEntry {
cluster: start,
entry: bad,
}
);
assert_eq!(findings_naming(&bytes, &format!("{bad:#x}")).len(), 1);
}
#[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::Io {
kind: std::io::ErrorKind::Other,
message: "x".to_string(),
},
ReadError::Parse(ParseError::TooShort {
structure: "x",
need: 1,
got: 0,
}),
ReadError::BadBootSector {
field: "x",
value: 1,
},
ReadError::AmbiguousClusterCount { clusters: 4086 },
ReadError::LargeCluster { bytes: 65536 },
ReadError::ClusterOutOfRange { cluster: 9 },
ReadError::BadChainEntry {
cluster: 9,
entry: 0,
},
ReadError::ChainTooLong {
start: 2,
clusters: 4,
},
ReadError::OrphanedLongName { index: 0 },
ReadError::LongNameChecksum {
index: 0,
found: 1,
expected: 2,
},
ReadError::LongNameTooLong {
index: 0,
units: 260,
},
ReadError::LongNamePadding { index: 0 },
ReadError::IllFormedLongName { index: 0 },
ReadError::UninterpretedShortName {
index: 0,
byte: 0x80,
},
ReadError::HostileName { index: 0 },
ReadError::ReservedCharacter {
index: 0,
field: "short",
code: 0x2b,
},
ReadError::IndistinguishableNames { index: 3, first: 2 },
ReadError::RepeatedDirectory { cluster: 3 },
ReadError::SizeWithoutAllocation { index: 0, size: 1 },
ReadError::DirectoryWithSize { index: 0, size: 1 },
ReadError::BadDotEntry {
detail: "x".to_string(),
},
ReadError::DotEntryTarget {
path: b"/x".to_vec(),
name: "..",
found: 3,
expected: 0,
},
ReadError::EntriesAfterEnd { index: 0 },
ReadError::DirectoryTooLong { index: 0, limit: 0 },
ReadError::MisplacedVolumeLabel { index: 0 },
ReadError::LabelWithDirectoryAttribute { index: 0 },
ReadError::SecondVolumeLabel { index: 0 },
ReadError::LabelBeginsWithSpace { index: 0 },
ReadError::LostClusters { count: 1, first: 2 },
ReadError::FreeCountOutOfRange {
stated: 9,
clusters: 8,
},
ReadError::FreeCountStale {
stated: 7,
counted: 8,
},
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 },
ReadError::BackupBootSectorDiffers { sector: 6 },
ReadError::BadInfoSector { sector: 1 },
ReadError::BadReservedEntry {
index: 1,
found: 0,
expected: 1,
},
ReadError::ChainTooShort {
start: 2,
size: 4096,
read: 512,
},
ReadError::MalformedTimestamp {
index: 0,
field: "modification time",
},
ReadError::SectorOutOfRange {
sector: 9,
total_sectors: 8,
},
ReadError::TableMismatch {
copy: 1,
cluster: 2,
first: 3,
other: 4,
},
ReadError::TablePaddingMismatch { copy: 1 },
ReadError::VolumeDirty,
ReadError::MediaFailure,
];
for err in all {
let anomaly = err.anomaly();
assert!(!anomaly.detail.is_empty(), "{err:?}");
let finding = crate::Deviation::to_finding(&anomaly, 512);
assert_eq!(finding.family, Family::Fat);
assert_eq!(finding.category, anomaly.category.as_str());
}
}
fn entry_of(image: &Image, name: &[u8; 11]) -> usize {
let bytes = image.as_bytes();
bytes
.as_chunks::<DIR_ENTRY_SIZE>()
.0
.iter()
.position(|slot| &slot[..11] == name)
.map(|n| n * DIR_ENTRY_SIZE)
.unwrap_or_else(|| panic!("no entry is named {}", String::from_utf8_lossy(name)))
}
fn ten_names() -> Image {
let m = |mode| Metadata::new(mode, TIME);
let mut tree = TreeBuilder::new().directory(b"/D".to_vec(), m(0o755));
for i in 0..10 {
tree = tree.file(format!("/D/N{i}.TXT").into_bytes(), b"x".to_vec(), m(0o644));
}
format(
tree,
64 << 20,
options().plan(PlanRequest::new(0).fat_type(FatTypeRequest::Exactly(FatType::Fat16))),
)
.expect("format")
}
#[test]
fn a_lookup_reads_a_directory_only_as_far_as_its_name() {
let image = ten_names();
let mut r = Reader::open_with(
Cursor::new(image.as_bytes()),
&OpenOptions::new().limits(Limits::new().max_walk_entries(3)),
)
.expect("open");
let dir = r.lookup(b"/D").expect("the directory");
assert!(matches!(
r.read_dir(&dir),
Err(ReadError::WalkTooLarge { limit: 3 })
));
for name in [&b"/D/N0.TXT"[..], b"/D/N9.TXT", b"/d/n9.txt"] {
assert!(
r.lookup(name).is_ok(),
"{} is past the cap and found",
String::from_utf8_lossy(name)
);
}
}
#[test]
fn an_entry_past_the_match_does_not_refuse_a_strict_lookup() {
let image = ten_names();
let mut bytes = image.as_bytes().to_vec();
let at = entry_of(&image, b"N5 TXT");
bytes[at] = b'/';
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("a strict open");
let dir = r.lookup(b"/D").expect("the directory");
assert!(matches!(
r.read_dir(&dir),
Err(ReadError::HostileName { .. })
));
assert!(r.lookup(b"/D/N2.TXT").is_ok(), "before the bad entry");
assert!(
matches!(r.lookup(b"/D/N8.TXT"), Err(ReadError::HostileName { .. })),
"past it, the lookup reads it on the way"
);
assert!(r.lookup(b"/D/n2.txt").is_err());
}
#[test]
fn a_walk_bound_is_reported_rather_than_silently_shortening_the_tree() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut r = Reader::open_with(
Cursor::new(image.as_bytes()),
&OpenOptions::new().limits(Limits::new().max_walk_entries(3)),
)
.expect("open");
assert!(matches!(
r.walk(),
Err(ReadError::WalkTooLarge { limit: 3 })
));
}
fn root_chained_through(
clusters: Option<u32>,
slot: impl Fn(usize) -> [u8; DIR_ENTRY_SIZE],
) -> (Vec<u8>, FatLayout) {
let opts = options().plan(
PlanRequest::new(0)
.cluster_size(ClusterSize::Sectors(1))
.reserved_sectors(ReservedSectors::Count(32))
.fat_type(FatTypeRequest::UndersizedFat32),
);
let image = format(TreeBuilder::new(), 8 << 20, opts).expect("format");
let layout = *image.layout();
let mut bytes = image.into_bytes();
let root = layout.fat32.expect("a FAT32 volume").root_cluster;
assert_eq!(root, 2, "the root is the first cluster");
let last = root + clusters.unwrap_or(layout.clusters) - 1;
assert!(last < layout.clusters + 2, "the volume holds the chain");
let table_bytes = layout.fat_sectors as usize * layout.bytes_per_sector as usize;
for copy in 0..layout.fats {
let start = at(&layout, layout.fat_start_sector(copy).expect("a table"));
let table = &mut bytes[start..start + table_bytes];
for cluster in root..=last {
let value = if cluster == last {
table::end_of_chain(layout.fat_type)
} else {
cluster + 1
};
assert!(table::write_entry(layout.fat_type, table, cluster, value));
}
}
let data = at(&layout, layout.first_data_sector);
let end = data + (last - root + 1) as usize * layout.bytes_per_cluster() as usize;
for (n, chunk) in bytes[data..end]
.as_chunks_mut::<DIR_ENTRY_SIZE>()
.0
.iter_mut()
.enumerate()
{
*chunk = slot(n);
}
(bytes, layout)
}
fn file_slot(name: &[u8]) -> [u8; DIR_ENTRY_SIZE] {
let mut slot = [0u8; DIR_ENTRY_SIZE];
slot[..11].copy_from_slice(name);
slot[11] = 0x20; let stamp = DosTimestamp::encode(TIME).expect("in range");
slot[22..24].copy_from_slice(&stamp.time.to_le_bytes());
slot[24..26].copy_from_slice(&stamp.date.to_le_bytes());
slot
}
fn root_chained_through_the_whole_volume() -> (Vec<u8>, FatLayout) {
root_chained_through(None, |_| file_slot(b"FILLER TXT"))
}
#[test]
fn a_directory_larger_than_the_cap_is_refused_before_it_is_gathered() {
let (bytes, layout) = root_chained_through_the_whole_volume();
assert!(
layout.clusters > 4096,
"the fixture is too small to be evidence: {} clusters",
layout.clusters
);
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().limits(Limits::new().max_walk_entries(16)),
)
.expect("open");
let root = r.root();
assert!(matches!(
r.read_dir(&root),
Err(ReadError::WalkTooLarge { limit: 16 })
));
assert!(matches!(
r.walk(),
Err(ReadError::WalkTooLarge { limit: 16 })
));
assert!(matches!(
r.chain(2),
Err(ReadError::WalkTooLarge { limit: 16 })
));
}
fn root_of_clusters(clusters: u32) -> Vec<u8> {
root_chained_through(Some(clusters), |n| {
file_slot(format!("F{n:07}TXT").as_bytes())
})
.0
}
#[test]
fn a_directory_past_the_format_s_size_is_read_whole_and_named() {
let per_cluster = 512 / DIR_ENTRY_SIZE as u64;
let at_bound = u32::try_from(MAX_DIRECTORY_BYTES / 512).expect("a cluster count");
let lenient = OpenOptions::new().policy(ReadPolicy::Lenient);
let finding = ReadError::DirectoryTooLong {
index: u32::try_from(MAX_DIRECTORY_ENTRIES).expect("an index"),
limit: MAX_DIRECTORY_BYTES,
}
.to_string();
let bytes = root_of_clusters(at_bound);
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
let root = r.root();
let entries = r.read_dir(&root).expect("a directory of the format's size");
assert_eq!(entries.len() as u64, MAX_DIRECTORY_ENTRIES);
let mut r = Reader::open_with(Cursor::new(bytes.as_slice()), &lenient).expect("open");
assert!(
!r.scan().anomalies().iter().any(|a| a.detail == finding),
"a directory of exactly the bound"
);
let bytes = root_of_clusters(at_bound + 1);
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
let root = r.root();
let err = r.read_dir(&root).expect_err("a strict read refuses it");
assert_eq!(err.to_string(), finding);
assert_eq!(err.anomaly().severity, Severity::Conformance);
assert!(r.lookup(b"/F0000009.TXT").is_ok());
let mut r = Reader::open_with(Cursor::new(bytes.as_slice()), &lenient).expect("open");
let root = r.root();
let entries = r.read_dir(&root).expect("a lenient read");
assert_eq!(entries.len() as u64, MAX_DIRECTORY_ENTRIES + per_cluster);
let last = format!("F{:07}.TXT", MAX_DIRECTORY_ENTRIES + per_cluster - 1);
assert_eq!(
entries.last().map(|e| e.name.as_slice()),
Some(last.as_bytes())
);
let report = r.scan();
let named: Vec<_> = report
.anomalies()
.iter()
.filter(|a| a.detail == finding)
.collect();
assert_eq!(named.len(), 1, "{:#?}", report.anomalies());
assert_eq!(named[0].severity, Severity::Conformance);
}
#[test]
fn a_scan_that_hit_the_cap_inside_one_directory_reports_nothing_lost() {
let (bytes, _) = root_chained_through_the_whole_volume();
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new()
.policy(ReadPolicy::Lenient)
.limits(Limits::new().max_walk_entries(16)),
)
.expect("open");
let report = r.scan();
assert!(
report
.anomalies()
.iter()
.any(|a| a.detail.contains("more than 16 names")),
"{:#?}",
report.anomalies()
);
assert!(
!report
.anomalies()
.iter()
.any(|a| a.detail.contains("reached by no chain")),
"{:#?}",
report.anomalies()
);
}
fn damaged(what: FatTypeRequest, damage: impl FnOnce(&mut [u8], &FatLayout)) -> ScanReport {
let image = image(64, what);
let layout = *image.layout();
let mut bytes = image.into_bytes();
damage(&mut bytes, &layout);
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open");
r.scan()
}
fn set_ext_flags(bytes: &mut [u8], layout: &FatLayout, flags: u16) {
let mut sectors = vec![0u32];
if let Some(backup) = layout.fat32.and_then(|f| f.backup_boot_sector) {
sectors.push(u32::from(backup));
}
for sector in sectors {
let off = at(layout, sector) + 40;
bytes[off..off + 2].copy_from_slice(&flags.to_le_bytes());
}
}
#[test]
fn a_chain_is_followed_through_the_table_the_volume_says_is_live() {
let pristine = image(512, FatTypeRequest::Exactly(FatType::Fat32));
let layout = *pristine.layout();
let want = {
let mut r = reader(&pristine);
let node = r.lookup(b"/a-long-file-name.text").expect("lookup");
r.read_data(&node).expect("read")
};
assert_eq!(want.len(), 5000, "the fixture file spans several clusters");
let names = reader(&pristine).walk().expect("walk").len();
let mut bytes = pristine.into_bytes();
let start = at(&layout, layout.fat_start_sector(0).expect("a first table"));
let len = at(&layout, layout.fat_sectors);
bytes[start..start + len].fill(0);
set_ext_flags(&mut bytes, &layout, 0x0081);
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("a strict open");
let node = r.lookup(b"/a-long-file-name.text").expect("lookup");
assert_eq!(
r.read_data(&node).expect("read through the live table"),
want,
"the bytes are the live table's, not the abandoned copy's"
);
assert_eq!(
r.walk().expect("walk").len(),
names,
"the tree is the live table's too"
);
let mut mirrored = bytes;
set_ext_flags(&mut mirrored, &layout, 0x0000);
let mut r = Reader::open(Cursor::new(mirrored.as_slice())).expect("open");
let read = r
.lookup(b"/a-long-file-name.text")
.and_then(|node| r.read_data(&node));
assert!(
matches!(read, Err(ReadError::BadChainEntry { entry: 0, .. })),
"with mirroring on the read goes through the emptied copy 0, whose entries are \
free and so continue no chain: {read:?}"
);
assert!(r.walk().is_err(), "nor does the tree walk through it");
}
#[test]
fn the_label_is_the_live_one_and_survives_the_leading_byte_substitution() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let live = reader(&image)
.volume_label()
.expect("read")
.expect("a label");
assert_eq!(live, b"FERROSYS");
let mut bytes = image.into_bytes();
let boot = bytes
.windows(11)
.position(|w| w == b"FERROSYS ")
.expect("the boot sector's copy");
let root = bytes
.windows(11)
.rposition(|w| w == b"FERROSYS ")
.expect("the root entry");
assert_ne!(boot, root, "the two copies are two places");
bytes[boot..boot + 11].copy_from_slice(b"STALECOPY ");
bytes[root] = NAME_DELETED;
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
assert_eq!(
r.volume_label().expect("read").as_deref(),
Some(&b"STALECOPY"[..]),
"a deleted entry is not the volume's label"
);
let mut restored = bytes.clone();
restored[root] = NAME_LEADING_E5;
restored[root + 1..root + 11].copy_from_slice(b"ABEL ");
let mut r = Reader::open_with(
Cursor::new(restored.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
assert_eq!(
r.volume_label().expect("read").expect("a label")[0],
0xE5,
"the substituted leading byte is put back"
);
}
#[test]
fn an_unknown_filesystem_version_is_reported_rather_than_scanned_clean() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat32), |bytes, layout| {
let mut sectors = vec![0u32];
if let Some(backup) = layout.fat32.and_then(|f| f.backup_boot_sector) {
sectors.push(u32::from(backup));
}
for sector in sectors {
let off = at(layout, sector) + 42;
bytes[off..off + 2].copy_from_slice(&1u16.to_le_bytes());
}
});
assert!(
report
.anomalies()
.iter()
.any(|a| a.detail.contains("BPB_FSVer is 0x0001")),
"{:#?}",
report.anomalies()
);
}
#[test]
fn a_live_table_the_volume_does_not_have_is_reported_rather_than_followed_blindly() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat32), |bytes, layout| {
set_ext_flags(bytes, layout, 0x0085);
});
assert!(
report.anomalies().iter().any(|a| {
a.severity == Severity::Integrity && a.detail.contains("names table 5")
}),
"{:#?}",
report.anomalies()
);
}
#[test]
fn a_name_carrying_terminal_control_bytes_is_escaped_where_it_enters_a_finding() {
let hostile = b"\x1b[2Jred\r";
let report = damaged(FatTypeRequest::Exactly(FatType::Fat16), |bytes, _| {
let at = bytes
.windows(11)
.position(|w| w == b"BOOTX64 EFI")
.expect("the fixture's short name is on disk");
bytes[at..at + 8].copy_from_slice(hostile);
bytes[at + 28..at + 32].copy_from_slice(&999_999u32.to_le_bytes());
});
let named: Vec<&str> = report
.anomalies()
.iter()
.map(|a| a.detail.as_str())
.filter(|d| d.contains("\\x1b"))
.collect();
assert!(
!named.is_empty(),
"a finding names the entry: {:#?}",
report.anomalies()
);
for detail in report.anomalies().iter().map(|a| &a.detail) {
assert!(
!detail.chars().any(char::is_control),
"a finding carries a raw control byte: {detail:?}"
);
}
let findings = report.to_report();
for rendered in [findings.to_table(), findings.to_json()] {
assert!(
!rendered.chars().any(|c| c.is_control() && c != '\n'),
"a rendered report carries a raw control byte: {rendered:?}"
);
}
}
#[test]
fn a_table_that_disagrees_with_its_mirror_is_an_integrity_finding() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat16), |bytes, layout| {
let second = layout.fat_start_sector(1).expect("two tables");
bytes[at(layout, second) + 8] ^= 0xFF;
});
assert!(
report
.anomalies()
.iter()
.any(|a| a.severity == Severity::Integrity
&& a.category == Category::AllocationTable),
"{:#?}",
report.anomalies()
);
assert!(report.has_fatal(ReadPolicy::Strict));
}
fn fat12_with_an_even_highest_cluster() -> (Vec<u8>, FatLayout) {
for mib in 1u64..8 {
let image = image(mib, FatTypeRequest::Exactly(FatType::Fat12));
let layout = *image.layout();
if (layout.clusters + 1).is_multiple_of(2) && layout.fats >= 2 {
return (image.into_bytes(), layout);
}
}
panic!("no FAT12 fixture in range has an even highest cluster");
}
#[test]
fn a_divergence_in_the_last_fat12_entry_is_a_mismatch_and_not_padding() {
let (mut bytes, layout) = fat12_with_an_even_highest_cluster();
let highest = layout.clusters + 1;
let shared = table::entry_offset(FatType::Fat12, highest) + 1;
let second = at(&layout, layout.fat_start_sector(1).expect("two tables"));
bytes[second + shared as usize] ^= 0x01;
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open");
match r.verify_tables() {
Err(ReadError::TableMismatch { copy, cluster, .. }) => {
assert_eq!(copy, 1);
assert_eq!(cluster, highest);
}
other => panic!("expected a mismatch at the last entry, got {other:?}"),
}
let report = r.scan();
assert!(
report.has_fatal(ReadPolicy::Strict),
"a table that disagrees about a live entry is not a remark: {:#?}",
report.anomalies()
);
let (mut bytes, layout) = fat12_with_an_even_highest_cluster();
let past = table::entry_offset(FatType::Fat12, layout.clusters + 1) + 2;
bytes[second + past as usize] ^= 0xFF;
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open");
assert!(matches!(
r.verify_tables(),
Err(ReadError::TablePaddingMismatch { copy: 1 })
));
}
#[test]
fn a_divergence_in_a_shared_fat12_byte_names_the_entry_that_differs() {
let (mut bytes, layout) = fat12_with_an_even_highest_cluster();
let second = at(&layout, layout.fat_start_sector(1).expect("two tables"));
let odd = 101u32;
let shared = table::entry_offset(FatType::Fat12, odd) as usize;
assert!(odd < layout.clusters + 1, "the fixture is too small");
let before = {
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
(
r.table_entry_in(0, odd - 1).expect("even entry"),
r.table_entry_in(0, odd).expect("odd entry"),
)
};
bytes[second + shared] ^= 0x10;
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open");
match r.verify_tables() {
Err(ReadError::TableMismatch {
copy,
cluster,
first,
other,
}) => {
assert_eq!(copy, 1);
assert_eq!(
cluster, odd,
"the shared byte was attributed to its neighbour"
);
assert_ne!(first, other, "a mismatch printed two identical values");
assert_eq!(first, before.1);
}
other => panic!("expected a mismatch at the odd entry, got {other:?}"),
}
let (mut bytes, _) = fat12_with_an_even_highest_cluster();
bytes[second + shared] ^= 0x01;
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open");
match r.verify_tables() {
Err(ReadError::TableMismatch {
cluster,
first,
other,
..
}) => {
assert_eq!(cluster, odd - 1);
assert_ne!(first, other);
assert_eq!(first, before.0);
}
other => panic!("expected a mismatch at the even entry, got {other:?}"),
}
}
#[test]
fn a_long_name_whose_checksum_does_not_match_is_an_integrity_finding() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat16), |bytes, layout| {
let root = at(
layout,
layout.root_dir_start_sector().expect("a root region"),
);
for slot in 1..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
let previous = root + (slot - 1) * DIR_ENTRY_SIZE;
if bytes[off + 11] != DirAttributes::LFN.bits()
&& bytes[previous + 11] == DirAttributes::LFN.bits()
{
bytes[off] = b'Z';
return;
}
}
panic!("the fixture holds no long-name run");
});
assert!(
report
.anomalies()
.iter()
.any(|a| a.detail.contains("checksums to")),
"{:#?}",
report.anomalies()
);
}
#[test]
fn a_first_cluster_outside_the_volume_is_a_structural_finding() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat16), |bytes, layout| {
let root = at(
layout,
layout.root_dir_start_sector().expect("a root region"),
);
for slot in 0..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
let attrs = bytes[off + 11];
let size = u32::from_le_bytes(bytes[off + 28..off + 32].try_into().unwrap());
if attrs != DirAttributes::LFN.bits() && size > 0 {
bytes[off + 26..off + 28].copy_from_slice(&0xFFFEu16.to_le_bytes());
return;
}
}
panic!("the fixture holds no file entry in the root");
});
assert!(
report.worst_severity() >= Some(Severity::Structural),
"{:#?}",
report.anomalies()
);
}
#[test]
fn clusters_allocated_and_reached_by_nothing_are_reported() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat16), |bytes, layout| {
let orphan = layout.clusters;
for copy in 0..layout.fats {
let start = at(layout, layout.fat_start_sector(copy).expect("a table"));
let off = start + table::entry_offset(FatType::Fat16, orphan) as usize;
bytes[off..off + 2].copy_from_slice(&0xFFFFu16.to_le_bytes());
}
});
assert!(
report
.anomalies()
.iter()
.any(|a| a.detail.contains("reached by no chain")),
"{:#?}",
report.anomalies()
);
}
#[test]
fn an_entry_recording_a_length_and_no_first_cluster_is_named_where_it_is_read() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let entry = entry_of(&image, b"EMPTY ");
let mut bytes = image.into_bytes();
bytes[entry + 28..entry + 32].copy_from_slice(&10u32.to_le_bytes());
let err = Reader::open(Cursor::new(bytes.as_slice()))
.expect("open")
.walk()
.expect_err("a strict read refuses it");
assert!(
matches!(err, ReadError::SizeWithoutAllocation { size: 10, .. }),
"{err}"
);
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("a lenient open");
let report = r.scan();
let found: Vec<_> = report
.anomalies()
.iter()
.filter(|a| a.detail.contains("no first cluster"))
.collect();
assert_eq!(found.len(), 1, "{:#?}", report.anomalies());
assert_eq!(found[0].severity, Severity::Structural);
assert!(!report.is_clean());
let node = r.lookup(b"/empty").expect("lookup");
assert!(matches!(
r.read_data(&node),
Err(ReadError::ChainTooShort {
start: 0,
size: 10,
read: 0
})
));
}
#[test]
fn a_backup_boot_sector_that_has_drifted_is_reported() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat32), |bytes, layout| {
let backup = layout
.fat32
.and_then(|f| f.backup_boot_sector)
.expect("a backup");
bytes[at(layout, u32::from(backup)) + 20] ^= 0xFF;
});
assert!(
report
.anomalies()
.iter()
.any(|a| a.category == Category::BootSector),
"{:#?}",
report.anomalies()
);
}
fn clear_entry_one(bytes: &mut [u8], layout: &FatLayout, bits: u32) {
let offset = table::entry_offset(layout.fat_type, 1) as usize;
for copy in 0..layout.fats {
let start = at(layout, layout.reserved_sectors + copy * layout.fat_sectors) + offset;
let width = if layout.fat_type == FatType::Fat32 {
4
} else {
2
};
let mut word = [0u8; 4];
word[..width].copy_from_slice(&bytes[start..start + width]);
let cleared = (u32::from_le_bytes(word) & !bits).to_le_bytes();
bytes[start..start + width].copy_from_slice(&cleared[..width]);
}
}
#[test]
fn the_status_bits_of_entry_one_are_a_state_and_not_a_bad_entry() {
for fat_type in [FatType::Fat16, FatType::Fat32] {
let (clean, no_error) = table::status_bits(fat_type);
for (bits, expected) in [
(clean, vec![ReadError::VolumeDirty]),
(no_error, vec![ReadError::MediaFailure]),
(
clean | no_error,
vec![ReadError::VolumeDirty, ReadError::MediaFailure],
),
] {
let report = damaged(FatTypeRequest::Exactly(fat_type), |bytes, layout| {
clear_entry_one(bytes, layout, bits);
});
let expected: Vec<Anomaly> = expected.iter().map(ReadError::anomaly).collect();
assert_eq!(report.anomalies(), expected, "{fat_type:?}, bits {bits:#x}");
assert!(!report.has_fatal(ReadPolicy::Strict), "{fat_type:?}");
}
let report = damaged(FatTypeRequest::Exactly(fat_type), |bytes, layout| {
clear_entry_one(bytes, layout, 1);
});
assert!(
matches!(
report.anomalies(),
[a] if a.category == Category::AllocationTable
&& a.severity == Severity::Conformance
),
"{fat_type:?}: {:#?}",
report.anomalies()
);
}
let report = damaged(FatTypeRequest::Exactly(FatType::Fat12), |bytes, layout| {
clear_entry_one(bytes, layout, 0x800);
});
assert!(
matches!(report.anomalies(), [a] if a.severity == Severity::Conformance),
"{:#?}",
report.anomalies()
);
}
#[test]
fn a_backup_boot_sector_is_compared_past_the_dirty_mark_and_no_further() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat32), |bytes, _| {
bytes[64 + 1] |= VOLUME_DIRTY;
});
assert_eq!(
report.anomalies(),
[ReadError::VolumeDirty.anomaly()],
"the state, once, and no stale backup"
);
let report = damaged(FatTypeRequest::Exactly(FatType::Fat32), |bytes, _| {
bytes[64 + 1] |= 0x02;
});
assert!(
matches!(
report.anomalies(),
[a] if a.category == Category::BootSector && a.severity == Severity::Conformance
),
"{:#?}",
report.anomalies()
);
}
#[test]
fn the_half_of_the_information_sector_signature_nothing_explains_is_checked() {
let report = damaged(FatTypeRequest::Exactly(FatType::Fat32), |bytes, layout| {
let info = at(
layout,
u32::from(layout.fat32.expect("a FAT32 layout").fs_info_sector),
);
bytes[info + FsInfo::TRAIL_OFFSET] ^= 0x01;
});
let found: Vec<_> = report
.anomalies()
.iter()
.filter(|a| a.category == Category::InfoSector)
.collect();
assert_eq!(found.len(), 1, "{:#?}", report.anomalies());
assert_eq!(found[0].severity, Severity::Cosmetic);
assert!(found[0].detail.contains("trailing signature"));
assert!(!report.has_fatal(ReadPolicy::Strict));
let report = damaged(FatTypeRequest::Exactly(FatType::Fat32), |bytes, layout| {
let info = at(
layout,
u32::from(layout.fat32.expect("a FAT32 layout").fs_info_sector),
);
bytes[info + FsInfo::TRAIL_OFFSET + 3] ^= 0xFF;
});
assert!(report.is_clean(), "{:#?}", report.anomalies());
}
#[test]
fn a_short_name_above_ascii_is_a_conformance_deviation_until_a_page_is_named() {
let opts =
options().plan(PlanRequest::new(0).fat_type(FatTypeRequest::Exactly(FatType::Fat16)));
let m = Metadata::new(0o644, TIME);
let src = TreeBuilder::new().file(b"/README.TXT".to_vec(), b"hi\n".to_vec(), m);
let built = format(src, 64 << 20, opts).expect("format");
let layout = *built.layout();
let mut bytes = built.into_bytes();
let root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
let mut placed = false;
for slot in 0..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
if &bytes[off..off + 11] == b"README TXT" {
bytes[off + 5] = 0x82;
placed = true;
break;
}
}
assert!(placed, "the fixture holds no README entry");
let mut strict = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
let root_node = strict.root();
assert!(matches!(
strict.read_dir(&root_node),
Err(ReadError::UninterpretedShortName { byte: 0x82, .. })
));
let mut lenient = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let root_node = lenient.root();
let names: Vec<Vec<u8>> = lenient
.read_dir(&root_node)
.expect("read")
.into_iter()
.map(|e| e.name)
.collect();
assert!(names.contains(&b"READM\x82.TXT".to_vec()), "{names:?}");
let report = lenient.scan();
assert_eq!(
report.worst_severity(),
Some(Severity::Conformance),
"{:#?}",
report.anomalies()
);
let mut named = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().charset(ShortNameCharset::Cp437),
)
.expect("open");
let root_node = named.root();
let names: Vec<Vec<u8>> = named
.read_dir(&root_node)
.expect("a strict read, with the page named")
.into_iter()
.map(|e| e.name)
.collect();
assert!(
names.contains(&"READMé.TXT".as_bytes().to_vec()),
"{names:?}"
);
let report = named.scan();
assert_eq!(report.worst_severity(), Some(Severity::Cosmetic));
assert!(!report.has_fatal(ReadPolicy::Strict));
}
#[test]
fn a_long_name_that_is_not_well_formed_utf16_is_read_with_a_replacement() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let mut bytes = image.into_bytes();
let root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
let mut placed = false;
for slot in 0..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
if bytes[off + 11] == DirAttributes::LFN.bits() && bytes[off] & !LFN_LAST_ENTRY == 1 {
bytes[off + 1..off + 3].copy_from_slice(&0xD800u16.to_le_bytes());
placed = true;
break;
}
}
assert!(placed, "the fixture holds no long-name entry");
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let root_node = r.root();
let names: Vec<Vec<u8>> = r
.read_dir(&root_node)
.expect("read")
.into_iter()
.map(|e| e.name)
.collect();
assert!(
names.iter().any(|n| n.starts_with("\u{FFFD}".as_bytes())),
"{names:?}"
);
assert!(
r.scan()
.anomalies()
.iter()
.any(|a| a.detail.contains("well-formed UTF-16"))
);
}
#[test]
fn an_orphaned_long_name_run_is_reported_however_the_run_ends() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let bytes = image.into_bytes();
let root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
let short_off = (0..layout.root_entries as usize)
.map(|slot| root + slot * DIR_ENTRY_SIZE)
.find(|&off| {
bytes[off + 11] == DirAttributes::LFN.bits() && bytes[off] == LFN_LAST_ENTRY | 1
})
.map(|off| off + DIR_ENTRY_SIZE)
.expect("the fixture holds a single-entry long-name run");
let orphans_of = |edit: &dyn Fn(&mut [u8])| -> usize {
let mut edited = bytes.clone();
edit(&mut edited[short_off..short_off + DIR_ENTRY_SIZE]);
let mut r = Reader::open_with(
Cursor::new(edited.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
r.scan()
.anomalies()
.iter()
.filter(|a| a.detail.contains("do not form a complete run"))
.count()
};
assert_eq!(orphans_of(&|_| {}), 0, "the fixture is clean");
assert_eq!(
orphans_of(&|slot| slot[0] = NAME_END),
1,
"at the end marker"
);
assert_eq!(
orphans_of(&|slot| slot[0] = NAME_DELETED),
1,
"at a deleted entry"
);
assert_eq!(
orphans_of(&|slot| slot[11] = DirAttributes::VOLUME_ID.bits()),
1,
"at the volume label"
);
assert!(
orphans_of(&|slot| {
slot[0] = LFN_LAST_ENTRY | 1;
slot[11] = DirAttributes::LFN.bits();
}) >= 1,
"at a second sequence start"
);
assert_eq!(
orphans_of(&|slot| {
slot[..11].copy_from_slice(b". ");
slot[11] = DirAttributes::DIRECTORY.bits();
}),
1,
"at a dot entry"
);
}
fn root_long_name_spelling(name: &str) -> Vec<u8> {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let mut bytes = image.into_bytes();
let root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
let units: Vec<u16> = name.encode_utf16().collect();
assert!(
units.len() < LFN_CHARS_PER_ENTRY,
"the name and its terminator must fit one entry"
);
for slot in 0..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
if bytes[off + 11] != DirAttributes::LFN.bits() || bytes[off] != LFN_LAST_ENTRY | 1 {
continue;
}
for i in 0..LFN_CHARS_PER_ENTRY {
let within = match i {
0..=4 => 1 + i * 2,
5..=10 => 14 + (i - 5) * 2,
_ => 28 + (i - 11) * 2,
};
let unit = match i.cmp(&units.len()) {
std::cmp::Ordering::Less => units[i],
std::cmp::Ordering::Equal => 0,
std::cmp::Ordering::Greater => 0xFFFF,
};
bytes[off + within..off + within + 2].copy_from_slice(&unit.to_le_bytes());
}
return bytes;
}
panic!("the fixture holds no single-entry long-name run");
}
fn root_short_name_of_efi(name: &[u8; 11]) -> Vec<u8> {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let mut bytes = image.into_bytes();
let root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
for slot in 0..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
if &bytes[off..off + 11] == b"EFI " {
bytes[off..off + 11].copy_from_slice(name);
return bytes;
}
}
panic!("the fixture holds no EFI entry");
}
fn assert_hostile_name_is_refused(bytes: &[u8], what: &str) {
let mut strict = Reader::open(Cursor::new(bytes)).expect("open");
let root_node = strict.root();
assert!(
matches!(
strict.read_dir(&root_node),
Err(ReadError::HostileName { .. })
),
"{what}: a strict read did not stop at it"
);
let mut lenient = Reader::open_with(
Cursor::new(bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let root_node = lenient.root();
for entry in lenient.read_dir(&root_node).expect("a lenient read") {
assert!(
!is_hostile_component(&entry.name),
"{what}: read_dir handed back {:?}",
String::from_utf8_lossy(&entry.name)
);
}
for entry in lenient.walk().expect("a lenient walk") {
for component in canonical_parts(&entry.path) {
assert!(
!is_hostile_component(component),
"{what}: the walk built {:?}",
String::from_utf8_lossy(&entry.path)
);
}
}
let report = lenient.scan();
assert!(!report.is_clean(), "{what}: the scan found nothing");
assert!(
report
.anomalies()
.iter()
.any(|a| a.severity == Severity::Structural
&& a.category == Category::Directory
&& a.detail.contains("no directory can hold")),
"{what}: {:#?}",
report.anomalies()
);
assert!(report.has_fatal(ReadPolicy::Strict), "{what}");
}
#[test]
fn a_long_name_a_directory_could_not_hold_is_refused_where_it_is_resolved() {
for name in ["..", ".", "a/b", "../etc"] {
assert_hostile_name_is_refused(&root_long_name_spelling(name), name);
}
}
#[test]
fn a_short_name_a_directory_could_not_hold_is_refused_where_it_is_resolved() {
for (name, what) in [(b"E/I ", "a separator"), (b"E\0I ", "a NUL")] {
assert_hostile_name_is_refused(&root_short_name_of_efi(name), what);
}
assert_hostile_name_is_refused(&root_short_name_of_efi(b" "), "an empty name");
}
#[cfg(feature = "tar")]
#[test]
fn an_archive_of_a_volume_holding_a_traversal_name_carries_no_traversal_member() {
let bytes = root_long_name_spelling("..");
let mut reader = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let mut archive = Vec::new();
crate::ArchiveSink::new(&mut archive)
.write_tree(&mut reader)
.expect("write the archive");
let mut members = 0usize;
for entry in tar::Archive::new(archive.as_slice())
.entries()
.expect("the archive lists its members")
{
let path = entry.expect("a member").path_bytes().to_vec();
for component in canonical_parts(&path) {
assert_ne!(
component,
b"..",
"the archive holds {:?}",
String::from_utf8_lossy(&path)
);
}
assert!(!path.contains(&0), "a member name carries a NUL");
members += 1;
}
assert!(members > 1, "the archive holds only {members} members");
}
#[test]
fn a_used_slot_past_the_end_marker_is_reported_and_never_handed_back() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let mut bytes = image.into_bytes();
let root = at(
&layout,
layout.root_dir_start_sector().expect("a root region"),
);
let mut placed = None;
for slot in 0..layout.root_entries as usize {
let off = root + slot * DIR_ENTRY_SIZE;
if bytes[off] == NAME_END {
let mut ghost = [0u8; DIR_ENTRY_SIZE];
ghost[..11].copy_from_slice(b"GHOST TXT");
ghost[11] = DirAttributes::ARCHIVE.bits();
let past = off + DIR_ENTRY_SIZE;
bytes[past..past + DIR_ENTRY_SIZE].copy_from_slice(&ghost);
placed = Some(slot + 1);
break;
}
}
assert!(placed.is_some(), "the fixture's root has no free slot");
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
let root_node = r.root();
let names: Vec<Vec<u8>> = r
.read_dir(&root_node)
.expect("read")
.into_iter()
.map(|e| e.name)
.collect();
assert!(
!names.contains(&b"GHOST.TXT".to_vec()),
"an entry past the end marker was handed back: {names:?}"
);
assert!(
r.scan()
.anomalies()
.iter()
.any(|a| a.detail.contains("follows the end marker")),
"{:#?}",
r.scan().anomalies()
);
let mut strict = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
let root_node = strict.root();
assert!(matches!(
strict.read_dir(&root_node),
Err(ReadError::EntriesAfterEnd { .. })
));
}
#[test]
fn a_scan_that_stopped_short_does_not_report_lost_clusters() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
for limits in [
Limits::new().max_walk_entries(2),
Limits::new().max_findings(1),
] {
let mut r = Reader::open_with(
Cursor::new(image.as_bytes()),
&OpenOptions::new()
.policy(ReadPolicy::Lenient)
.limits(limits),
)
.expect("open");
let report = r.scan();
assert!(
!report
.anomalies()
.iter()
.any(|a| a.detail.contains("reached by no chain")),
"a scan that stopped short reported lost clusters: {:#?}",
report.anomalies()
);
}
let mut r = Reader::open(Cursor::new(image.as_bytes())).expect("open");
assert!(r.scan().is_clean());
}
#[test]
fn a_scan_that_never_looked_is_not_a_clean_verdict() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let mut r = Reader::open_with(
Cursor::new(image.as_bytes()),
&OpenOptions::new()
.policy(ReadPolicy::Lenient)
.limits(Limits::new().max_findings(0)),
)
.expect("open");
let report = r.scan();
assert!(report.anomalies().is_empty());
assert!(report.is_truncated());
assert!(!report.is_clean(), "a truncated report claimed a verdict");
assert!(report.to_report().to_json().contains("\"clean\":false"));
}
#[test]
fn a_chain_that_loops_is_bounded_rather_than_followed() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let mut bytes = image.into_bytes();
let start = {
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
let node = r.lookup(b"/a-long-file-name.text").expect("lookup");
match node.storage {
Storage::Chain(start) => start,
_ => panic!("the fixture's multi-cluster file owns no chain"),
}
};
for copy in 0..layout.fats {
let off = at(&layout, layout.fat_start_sector(copy).expect("a table"))
+ table::entry_offset(FatType::Fat16, start + 1) as usize;
bytes[off..off + 2].copy_from_slice(&(start as u16).to_le_bytes());
}
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
assert!(matches!(
r.chain(start),
Err(ReadError::ChainTooLong { .. })
));
let mut cycled = bytes.clone();
let dir_start = {
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
let node = r.lookup(b"/EFI").expect("lookup");
match node.storage {
Storage::Chain(start) => start,
_ => panic!("a FAT16 subdirectory owns a chain"),
}
};
for copy in 0..layout.fats {
let off = at(&layout, layout.fat_start_sector(copy).expect("a table"))
+ table::entry_offset(FatType::Fat16, dir_start) as usize;
cycled[off..off + 2].copy_from_slice(&(dir_start as u16).to_le_bytes());
}
let (source, reads) = crate::io::Counting::new(cycled);
let mut counted =
Reader::open_with(source, &OpenOptions::new().policy(ReadPolicy::Lenient))
.expect("open");
let dir = counted.lookup(b"/EFI").expect("lookup");
let before = reads.borrow().len();
assert!(
matches!(counted.read_dir(&dir), Err(ReadError::ChainTooLong { .. })),
"a directory whose chain cycles is refused"
);
let cost = reads.borrow().len() - before;
assert!(
cost < 64,
"a directory cycling on one cluster cost {cost} reads"
);
assert!(!r.scan().is_clean());
}
#[test]
fn a_chain_looping_onto_itself_is_told_apart_from_a_cluster_two_chains_share() {
let image = image(64, FatTypeRequest::Exactly(FatType::Fat16));
let layout = *image.layout();
let mut bytes = image.into_bytes();
let start = {
let mut r = Reader::open(Cursor::new(bytes.as_slice())).expect("open");
let node = r.lookup(b"/a-long-file-name.text").expect("lookup");
match node.storage {
Storage::Chain(start) => start,
_ => panic!("the fixture's multi-cluster file owns no chain"),
}
};
for copy in 0..layout.fats {
let off = at(&layout, layout.fat_start_sector(copy).expect("a table"))
+ table::entry_offset(FatType::Fat16, start + 1) as usize;
bytes[off..off + 2].copy_from_slice(&(start as u16).to_le_bytes());
}
let mut r = Reader::open_with(
Cursor::new(bytes.as_slice()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.expect("open");
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 {start} returns to cluster {start}"
)),
"{said}"
);
assert!(
said.contains("a-long-file-name.text"),
"the owning path rides along: {said}"
);
assert!(
!report
.anomalies()
.iter()
.any(|a| a.detail.contains("another chain")),
"a loop is not a cross-link: {}",
report.to_report().to_table()
);
}
#[test]
fn the_reader_never_panics_on_mangled_images() {
let image = image(2, FatTypeRequest::Exactly(FatType::Fat12)).into_bytes();
fn drive(bytes: &[u8]) {
for options in [
OpenOptions::new(),
OpenOptions::new().policy(ReadPolicy::Lenient),
OpenOptions::new()
.policy(ReadPolicy::Lenient)
.charset(ShortNameCharset::Cp437),
OpenOptions::new().base(512).policy(ReadPolicy::Lenient),
] {
let Ok(mut r) = Reader::open_with(Cursor::new(bytes), &options) else {
continue;
};
let _ = r.verify_tables();
let _ = r.info_sector();
let _ = r.volume_label();
let _ = r.scan();
if let Ok(entries) = r.walk() {
for e in &entries {
let _ = r.read_data(&e.node);
if let Storage::Chain(start) = e.node.storage {
let _ = r.chain(start);
}
}
for e in &entries {
let _ = r.lookup(&e.path);
}
}
for path in [&b"/"[..], b"/../..", b"/a/b/c", b"//./"] {
let _ = r.lookup(path);
}
}
}
drive(&image);
for (off, len, fill) in [
(11usize, 2usize, 0xffu8), (13, 1, 0x00), (14, 2, 0xff), (16, 1, 0xff), (17, 2, 0xff), (19, 2, 0xff), (22, 2, 0xff), (32, 4, 0xff), ] {
let mut mangled = image.clone();
mangled[off..off + len].fill(fill);
drive(&mangled);
}
for len in [0usize, 1, 511, 512, 513, 1024, 4096, 65_536] {
drive(&image[..len.min(image.len())]);
}
let mut flip = image.clone();
let span = flip.len().min(96 * 1024);
let mut i = 0usize;
while i < span {
let orig = flip[i];
flip[i] ^= 0xff;
drive(&flip);
flip[i] = orig;
i += 251; }
drive(&vec![0x00u8; 8192]);
drive(&vec![0xffu8; 8192]);
let ramp: Vec<u8> = (0..8192u32).map(|k| (k % 256) as u8).collect();
drive(&ramp);
}
}