Struct InstanceRawSubdir

pub struct InstanceRawSubdir {
    dir: CheckedDir,
    flock_guard: Arc<LockFileGuard>,
}

Available on crate feature state-dir only.

Subdirectory within an instance’s state, for raw filesystem operations

Dereferences to fs_mistrust::CheckedDir and can be used mostly like one. Obtained from InstanceStateHandle::raw_subdir.

Existence of this value implies exclusive access to the instance.

If you need to manage the lock, and the directory path, separately, raw_lock_guard will help.

Fields

dir: CheckedDir

The actual directory, as a [fs_mistrust::CheckedDir]

flock_guard: Arc<LockFileGuard>

Clone of the InstanceStateHandle’s lock

Methods from Deref<Target = CheckedDir>

pub fn make_directory<P>(&self, path: P) -> Result<(), Error>

where P: AsRef<Path>,

Construct a new directory within this CheckedDir, if it does not already exist.

path must be a relative path to the new directory, containing no .. components.

pub fn make_secure_directory<P>(&self, path: P) -> Result<CheckedDir, Error>

where P: AsRef<Path>,

Construct a new CheckedDir within this CheckedDir

Creates the directory if it does not already exist.

path must be a relative path to the new directory, containing no .. components.

pub fn file_access(&self) -> FileAccess<'_>

Create a new FileAccess for reading or writing files within this directory.

pub fn open<P>(&self, path: P, options: &OpenOptions) -> Result<File, Error>

where P: AsRef<Path>,

Open a file within this CheckedDir, using a set of OpenOptions.

path must be a relative path to the new directory, containing no .. components. We check, but do not create, the file’s parent directories. We check the file’s permissions after opening it. If the file already exists, it must not be a symlink.

If the file is created (and this is a unix-like operating system), we always create it with mode 600, regardless of any mode options set in options.

pub fn read_directory<P>(&self, path: P) -> Result<ReadDir, Error>

where P: AsRef<Path>,

List the contents of a directory within this [CheckedDir].

path must be a relative path, containing no .. components. Before listing the directory, we verify that that no untrusted user is able change its contents or make it point somewhere else.

The return value is an iterator as returned by std::fs::ReadDir. We do not check any properties of the elements of this iterator.

pub fn remove_file<P>(&self, path: P) -> Result<(), Error>

where P: AsRef<Path>,

Remove a file within this [CheckedDir].

path must be a relative path, containing no .. components.

Note that we ensure that the parent of the file to be removed is unmodifiable by any untrusted user, but we do not check any permissions on the file itself, since those are irrelevant to removing it.

pub fn as_path(&self) -> &Path

Return a reference to this directory as a Path.

Note that this function lets you work with a broader collection of functions, including functions that might let you access or create a file that is accessible by non-trusted users. Be careful!

pub fn join<P>(&self, path: P) -> Result<PathBuf, Error>

where P: AsRef<Path>,

Return a new PathBuf containing this directory’s path, with path appended to it.

Return an error if path has any components that could take us outside of this directory.

pub fn read_to_string<P>(&self, path: P) -> Result<String, Error>

where P: AsRef<Path>,

Read the contents of the file at path within this directory, as a String, if possible.

Return an error if path is absent, if its permissions are incorrect, if it has any components that could take us outside of this directory, or if its contents are not UTF-8.

pub fn read<P>(&self, path: P) -> Result<Vec<u8>, Error>

where P: AsRef<Path>,

Read the contents of the file at path within this directory, as a vector of bytes, if possible.

Return an error if path is absent, if its permissions are incorrect, or if it has any components that could take us outside of this directory.

pub fn write_and_replace<P, C>(&self, path: P, contents: C) -> Result<(), Error>

where P: AsRef<Path>, C: AsRef<[u8]>,

Store contents into the file located at path within this directory.

We won’t write to path directly: instead, we’ll write to a temporary file in the same directory as path, and then replace path with that temporary file if we were successful. (This isn’t truly atomic on all file systems, but it’s closer than many alternatives.)

Limitations

This function will clobber any existing files with the same name as path but with the extension tmp. (That is, if you are writing to “foo.txt”, it will replace “foo.tmp” in the same directory.)

This function may give incorrect behavior if multiple threads or processes are writing to the same file at the same time: it is the programmer’s responsibility to use appropriate locking to avoid this.

pub fn metadata<P>(&self, path: P) -> Result<Metadata, Error>

where P: AsRef<Path>,

Return the Metadata of the file located at path.

path must be a relative path, containing no .. components. We check the file’s parent directories, and the file’s permissions. If the file exists, it must not be a symlink.

Returns [Error::NotFound] if the file does not exist.

Return an error if path is absent, if its permissions are incorrect¹, if the permissions of any of its the parent directories are incorrect, or if it has any components that could take us outside of this directory.

---

1. the permissions are incorrect if the path is readable or writable by untrusted users ↩

pub fn verifier(&self) -> Verifier<'_>

Create a [Verifier] with the appropriate rules for this CheckedDir.

Trait Implementations

impl Clone for InstanceRawSubdir

fn clone(&self) -> InstanceRawSubdir

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ContainsInstanceStateGuard for InstanceRawSubdir

fn raw_lock_guard(&self) -> Arc<LockFileGuard>

Obtain a raw clone of the underlying filesystem lock

impl Debug for InstanceRawSubdir

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

Formats the value using the given formatter.

impl Deref for InstanceRawSubdir

type Target = CheckedDir

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.