Struct StableDirectory 

pub struct StableDirectory { /* private fields */ }

Retained directory capability whose children are opened without following links or reparse points.

Implementations

impl StableDirectory

pub fn try_clone(&self) -> Result<Self>

Duplicate this retained directory capability without resolving its path again.

Errors

Returns an error if the retained directory identity changed or the OS cannot duplicate its handle.

pub fn lock_shared(&self) -> Result<()>

Acquire a cooperative shared lock on this retained Unix directory inode.

Windows directory handles cannot be byte-range locked; callers use a retained regular coordination file there instead.

pub fn lock_exclusive(&self) -> Result<()>

Acquire a cooperative exclusive lock on this retained Unix directory inode.

pub fn try_lock_exclusive(&self) -> Result<bool>

Try to acquire a cooperative exclusive lock on this retained Unix directory inode.

pub fn unlock(&self) -> Result<()>

Release this retained Unix directory inode’s cooperative lock.

pub fn open(path: &Path) -> Result<Self>

Open and retain a real directory at path.

pub fn from_retained_handle( path: PathBuf, handle: OpenedDirectoryHandle, identity: FileIdentity, ) -> Result<Self, DirectoryValidationError>

Adopt an already retained handle and expected identity, validating both the named path and the handle before issuing a directory capability.

pub fn as_file(&self) -> &File

Borrow the retained handle for native volume queries and cooperative locks. Callers must revalidate around namespace-sensitive operations.

pub fn path(&self) -> &Path

Return the named path associated with this capability.

pub fn into_handle(self) -> OpenedDirectoryHandle

Transfer the policy-proven native handle for adoption by another capability.

pub fn revalidate_named_detailed(&self) -> Result<(), DirectoryValidationError>

Require that the named path and retained handle still identify this ordinary directory, returning a typed failure stage for policy adapters.

pub fn revalidate_named(&self) -> Result<()>

Require that the named path still identifies this retained directory.

pub fn open_child_directory(&self, name: &OsStr) -> Result<Self>

Open one real child directory relative to this capability.

pub fn create_child_directory(&self, name: &OsStr) -> Result<Self>

Create one child directory if absent, then retain it.

pub fn open_child_file(&self, name: &OsStr) -> Result<File>

Open one regular child without following links or reparse points.

pub fn revalidate_child_file(&self, name: &OsStr, file: &File) -> Result<()>

Revalidate a retained regular child against its current named path.

Performs the same fresh directory and child observations as opening the child, without replacing the retained handle or its seek position.

pub fn open_publishing_child_file( &self, name: &OsStr, expected: FileIdentity, ) -> Result<File>

Reopen an already-admitted private publication source with write access for its file barrier and Windows delete sharing for its native rename. Ordinary immutable readers retain their existing anti-delete sharing.

pub fn visit_regular_files( &self, remaining: &mut usize, visit: &mut impl FnMut(&File) -> Result<()>, ) -> Result<()>

Visit regular descendants through retained, no-follow directory handles.

Every child is opened relative to its retained parent and revalidated before it reaches visit. Links and non-regular objects are skipped.

Errors

Returns an error if traversal exceeds remaining, a retained identity changes, directory enumeration fails, or visit fails. Targets without descriptor-relative directory enumeration return Unsupported.

pub fn create_child_file(&self, name: &OsStr) -> Result<File>

Create one new regular child without following links or reparse points.

pub fn create_replaceable_child_file(&self, name: &OsStr) -> Result<File>

Create a new regular child whose retained handle permits an atomic namespace replacement while it remains open.

pub fn create_unpublished_replaceable_child( &self, name: &OsStr, ) -> Result<UnpublishedArtifactGuard>

Exclusively create one replaceable child and immediately bind cleanup ownership to its retained descriptor identity.

Errors

Returns an error when creation, identity capture, or directory-capability cloning fails. Setup failure removes the exact created inode when safe.

pub fn open_or_create_child_file(&self, name: &OsStr) -> Result<File>

Open an existing regular child for read/write, or create it once.

pub fn child_names(&self) -> Result<Vec<OsString>>

Enumerate child names while retaining this directory capability.

pub fn child_names_bounded(&self, limit: usize) -> Result<Vec<OsString>>

Enumerate no more than limit child names from this retained directory. Returns InvalidData instead of materializing an attacker-sized sibling inventory when the bound is exceeded.

pub fn link_child_into( &self, source_name: &OsStr, source: &File, expected_source: FileIdentity, destination: &Self, destination_name: &OsStr, ) -> Result<(File, FileIdentity)>

Create a hard link between retained source and destination directories.

pub fn unlink_child_if_identity( &self, name: &OsStr, expected: FileIdentity, ) -> Result<()>

Remove a child under the caller’s held cooperative exclusive lifecycle guard, only while its current named identity matches expected.

pub fn remove_child_directory_if_identity( &self, name: &OsStr, expected: FileIdentity, ) -> Result<()>

Remove one empty child directory only while its retained and named identities still match. Callers must first authenticate and empty the directory through the returned child capability.

pub fn replace_child( &self, temporary: &OsStr, expected_temporary: FileIdentity, target: &OsStr, ) -> Result<()>

Atomically publish a retained temporary child as target within this retained directory. Cooperative publishers must serialize the target.

pub fn replace_child_typed( &self, temporary: &OsStr, expected_temporary: FileIdentity, target: &OsStr, ) -> Result<(), ReplaceFileError>

Replace one child while retaining native visibility uncertainty.

pub fn replace_authenticated_child( &self, temporary: &OsStr, expected_temporary: FileIdentity, target: &OsStr, expected_target: FileIdentity, ) -> Result<()>

Atomically replace an authenticated prior child, which may share its inode with immutable payloads or active snapshots. The source must be private. Callers must authenticate the prior contents and serialize publishers; this operation checks identity and never writes to the prior inode.

pub fn replace_authenticated_child_typed( &self, temporary: &OsStr, expected_temporary: FileIdentity, target: &OsStr, expected_target: FileIdentity, ) -> Result<(), ReplaceFileError>

Replace an authenticated prior child without losing native error state.

pub fn install_child( &self, temporary: &OsStr, expected_temporary: FileIdentity, target: &OsStr, ) -> Result<()>

Atomically install a retained temporary child without replacing an existing target. This is the creation authority for durable control records whose first publication must never overwrite competing state.

Errors

Returns an I/O error when either name is invalid, the retained source identity changed, the target already exists, or durable installation and identity revalidation fail.

pub fn install_child_typed( &self, temporary: &OsStr, expected_temporary: FileIdentity, target: &OsStr, ) -> Result<(), ReplaceFileError>

Preserve whether create-only publication definitely did not install or reached a native visibility boundary whose result needs reconciliation.

pub fn sync(&self) -> Result<()>

Flush this retained directory capability.

pub fn identity(&self) -> FileIdentity

Return the retained native identity.

Trait Implementations

impl Debug for StableDirectory

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

Formats the value using the given formatter.