Skip to main content

DiskTree

Struct DiskTree 

Source
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

Source

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.

Source

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.

Source

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.

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

Source

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.

Source

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.

Source

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§

Source§

impl Debug for DiskTree

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl ParallelTree for DiskTree

Source§

impl Tree for DiskTree

Source§

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>

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>

The text of the file at path. Read more
Source§

fn list(&self, path: &RelPath) -> Result<Vec<Entry>, TreeError>

The entries of the directory at path, sorted by name. Read more
Source§

fn entry(&self, path: &RelPath) -> Result<Option<EntryKind>, TreeError>

What is at path, or None when nothing is. Read more
Source§

fn identity(&self, path: &RelPath) -> Result<FileId, TreeError>

The identity of the file at path, without reading it: the identity Tree::read_unseen gives when every identity counts as seen. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> EvidenceLease for T
where T: Debug + Send + Sync,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.