pub struct DiskTree { /* private fields */ }Expand description
A tree read from a directory on disk.
The root is canonicalised once, in DiskTree::new. Unix retains its
original directory description. Linux refuses relocation outside the
canonical scope; replacement at that pathname cannot retarget the tree.
A symlink inside the tree is followed only when its target is also inside it.
Implementations§
Source§impl DiskTree
impl DiskTree
Sourcepub fn capture_file(
&self,
path: &RelPath,
max_bytes: u64,
) -> Result<CapturedFile, TreeError>
pub fn capture_file( &self, path: &RelPath, max_bytes: u64, ) -> Result<CapturedFile, TreeError>
Capture bytes, identity and permissions through one verified regular handle.
The type and permissions are checked again after reading. Symlinks are
followed under the same containment rules as Tree::read_bytes. Ownership,
ACLs and extended attributes are not captured by this operation.
§Errors
The errors of Tree::read_bytes, or an interrupted observation when
the file’s type or permissions change during the read.
Sourcepub fn capture_directory(
&self,
path: &RelPath,
) -> Result<CapturedDirectory, TreeError>
pub fn capture_directory( &self, path: &RelPath, ) -> Result<CapturedDirectory, TreeError>
Capture a complete sorted listing and the verified directory’s identity.
§Errors
The errors of super::Tree::list. A directory symlink is refused.
Sourcepub fn capture_directory_bounded(
&self,
path: &RelPath,
max_entries: usize,
) -> Result<CapturedDirectory, TreeError>
pub fn capture_directory_bounded( &self, path: &RelPath, max_entries: usize, ) -> Result<CapturedDirectory, TreeError>
Capture complete membership, refusing before collecting more than the bound.
Both verified observations use max_entries; no truncated listing is returned.
§Errors
The errors of Self::capture_directory, or an InvalidData I/O cause
naming this directory when its membership exceeds max_entries.
Sourcepub fn capture_link(&self, path: &RelPath) -> Result<CapturedLink, TreeError>
pub fn capture_link(&self, path: &RelPath) -> Result<CapturedLink, TreeError>
Capture a link through its verified containing-directory handle.
The target is not followed, so dangling and outside-pointing links can be described safely. This does not authorize materializing or following them elsewhere. Native Unix captures compare the link identity and exact target spelling before and after reading; other hosts refuse explicitly.
§Errors
Foreign authorities, outside parents, a non-link, a changed link, an unsupported host or a failed host operation refuse without a capture.
Source§impl DiskTree
impl DiskTree
Sourcepub fn new(root: impl AsRef<Path>) -> Result<Self, TreeError>
pub fn new(root: impl AsRef<Path>) -> Result<Self, TreeError>
Open a tree rooted at root, canonicalising it once.
A symlinked root is followed: the tree is rooted at its target.
§Errors
Returns TreeError::NotFound when the root does not exist,
TreeError::NotRegular when it is not a directory, and
TreeError::SymlinkLoop or TreeError::Io when the operating
system fails or cannot verify a handle against the root.
Sourcepub fn directory_handle(&self) -> Result<File, TreeError>
pub fn directory_handle(&self) -> Result<File, TreeError>
Clone the original Linux workspace directory description.
This is a path-only handle, suitable for descriptor-relative operations. An explicit metadata publisher can share it with this Tree rather than reopening a pathname that could now name another directory. Directory synchronization requires a separately opened, verified readable handle. Returning this handle does not make the inspected source immutable.
§Errors
Refuses a root outside its admitted canonical scope or a failure to inspect or clone the directory descriptor.
Sourcepub fn read_unseen_bytes(
&self,
path: &RelPath,
max_bytes: u64,
seen: &dyn Fn(&FileId) -> bool,
) -> Result<OpenedBytes, TreeError>
pub fn read_unseen_bytes( &self, path: &RelPath, max_bytes: u64, seen: &dyn Fn(&FileId) -> bool, ) -> Result<OpenedBytes, TreeError>
Take the actual file identity and read bytes from that same verified open.
An identity accepted by seen returns super::OpenedBytes::Seen
without reading its payload or applying the byte ceiling to that payload.
Otherwise the complete bytes obey Tree::read_bytes.
§Errors
As Tree::read_bytes, including identity and handle verification failures.
Trait Implementations§
impl ParallelTree for DiskTree
Source§impl Tree for DiskTree
impl Tree for DiskTree
Source§fn read_bytes(
&self,
path: &RelPath,
max_bytes: u64,
) -> Result<Vec<u8>, TreeError>
fn read_bytes( &self, path: &RelPath, max_bytes: u64, ) -> Result<Vec<u8>, TreeError>
The file is checked against the root before and after reading. At most
max_bytes + 1 bytes are read, and the extra byte makes the read
refuse. No UTF-8 validation or text conversion is applied.
Source§fn read_unseen(
&self,
path: &RelPath,
max_bytes: u64,
seen: &dyn Fn(&FileId) -> bool,
) -> Result<Opened, TreeError>
fn read_unseen( &self, path: &RelPath, max_bytes: u64, seen: &dyn Fn(&FileId) -> bool, ) -> Result<Opened, TreeError>
The identity is, on Unix, the device and inode of the verified handle, and on Windows the path the system gives for it, below the root; the text, when it is read, comes from the same handle.
Source§fn read(&self, path: &RelPath, max_bytes: u64) -> Result<String, TreeError>
fn read(&self, path: &RelPath, max_bytes: u64) -> Result<String, TreeError>
path. Read moreSource§fn list(&self, path: &RelPath) -> Result<Vec<Entry>, TreeError>
fn list(&self, path: &RelPath) -> Result<Vec<Entry>, TreeError>
path, sorted by name. Read moreAuto Trait Implementations§
impl Forget for DiskTree
impl Freeze for DiskTree
impl Move for DiskTree
impl RefUnwindSafe for DiskTree
impl Send for DiskTree
impl Sync for DiskTree
impl Unpin for DiskTree
impl UnsafeUnpin for DiskTree
impl UnwindSafe for DiskTree
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<T> EvidenceLease for T
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more