Struct tor_persist::state_dir::InstanceRawSubdir
source · pub struct InstanceRawSubdir { /* private fields */ }
state-dir
only.Expand description
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.
Methods from Deref<Target = CheckedDir>§
sourcepub fn make_directory<P>(&self, path: P) -> Result<(), Error>
pub fn make_directory<P>(&self, path: P) -> Result<(), Error>
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.
sourcepub fn make_secure_directory<P>(&self, path: P) -> Result<CheckedDir, Error>
pub fn make_secure_directory<P>(&self, path: P) -> Result<CheckedDir, Error>
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.
sourcepub fn open<P>(&self, path: P, options: &OpenOptions) -> Result<File, Error>
pub fn open<P>(&self, path: P, options: &OpenOptions) -> Result<File, Error>
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
.
sourcepub fn read_directory<P>(&self, path: P) -> Result<ReadDir, Error>
pub fn read_directory<P>(&self, path: P) -> Result<ReadDir, Error>
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.
sourcepub fn remove_file<P>(&self, path: P) -> Result<(), Error>
pub fn remove_file<P>(&self, path: P) -> Result<(), Error>
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.
sourcepub fn as_path(&self) -> &Path
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!
sourcepub fn join<P>(&self, path: P) -> Result<PathBuf, Error>
pub fn join<P>(&self, path: P) -> Result<PathBuf, Error>
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.
sourcepub fn read_to_string<P>(&self, path: P) -> Result<String, Error>
pub fn read_to_string<P>(&self, path: P) -> Result<String, Error>
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.
sourcepub fn read<P>(&self, path: P) -> Result<Vec<u8>, Error>
pub fn read<P>(&self, path: P) -> Result<Vec<u8>, Error>
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.
sourcepub fn write_and_replace<P, C>(&self, path: P, contents: C) -> Result<(), Error>
pub fn write_and_replace<P, C>(&self, path: P, contents: C) -> Result<(), Error>
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.
Trait Implementations§
source§impl Clone for InstanceRawSubdir
impl Clone for InstanceRawSubdir
source§fn clone(&self) -> InstanceRawSubdir
fn clone(&self) -> InstanceRawSubdir
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl ContainsInstanceStateGuard for InstanceRawSubdir
impl ContainsInstanceStateGuard for InstanceRawSubdir
source§fn raw_lock_guard(&self) -> Arc<LockFileGuard>
fn raw_lock_guard(&self) -> Arc<LockFileGuard>
source§impl Debug for InstanceRawSubdir
impl Debug for InstanceRawSubdir
Auto Trait Implementations§
impl Freeze for InstanceRawSubdir
impl RefUnwindSafe for InstanceRawSubdir
impl Send for InstanceRawSubdir
impl Sync for InstanceRawSubdir
impl Unpin for InstanceRawSubdir
impl UnwindSafe for InstanceRawSubdir
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> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
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