Struct obnth::Dir

pub struct Dir { /* fields omitted */ }

A wrapper around a directory file descriptor that allows opening files within that directory.

Implementations

impl Dir

pub fn open<P: AsPath>(path: P) -> Result<Self>

Open the specified directory.

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

Open the parent directory of this directory, without checking if it's open to the root directory.

If this directory is open to the root directory, this method will return a new directory open to the same directory (similarly to try_clone()).

pub fn parent(&self) -> Result<Option<Self>>

Open the parent directory of this directory.

This returns Ok(None) if this directory is open to the root directory.

pub fn sub_dir<P: AsPath>(
    &self,
    path: P,
    lookup_flags: LookupFlags
) -> Result<Self>

Open a subdirectory of this directory.

path or one of its components can refer to a symlink (unless LookupFlags::NO_SYMLINKS is passed), but the specified subdirectory must be contained within this directory.

pub fn create_dir<P: AsPath>(
    &self,
    path: P,
    mode: mode_t,
    lookup_flags: LookupFlags
) -> Result<()>

Create a directory within this directory.

pub fn remove_dir<P: AsPath>(
    &self,
    path: P,
    lookup_flags: LookupFlags
) -> Result<()>

Remove a subdirectory of this directory.

pub fn remove_file<P: AsPath>(
    &self,
    path: P,
    lookup_flags: LookupFlags
) -> Result<()>

Remove a file within this directory.

pub fn symlink<P: AsPath, T: AsPath>(
    &self,
    path: P,
    target: T,
    lookup_flags: LookupFlags
) -> Result<()>

Create a symlink within this directory.

path specifies the path where the symlink is created, and target specifies the file that the symlink will point to. Note that the order is swapped compared to the C symlink() function (and Rust's std::os::unix::fs::symlink()).

pub fn read_link<P: AsPath>(
    &self,
    path: P,
    lookup_flags: LookupFlags
) -> Result<PathBuf>

Read the contents of the specified symlink.

pub fn local_rename<P: AsPath, R: AsPath>(
    &self,
    old: P,
    new: R,
    lookup_flags: LookupFlags
) -> Result<()>

Rename a file in this directory.

This is exactly equivalent to rename(self, old, self, new, lookup_flags).

pub fn list_self(&self) -> Result<ReadDirIter>

List the contents of this directory.

pub fn list_dir<P: AsPath>(
    &self,
    path: P,
    lookup_flags: LookupFlags
) -> Result<ReadDirIter>

List the contents of the specified subdirectory.

This is equivalent to self.sub_dir(path, lookup_flags)?.list_self(), but more efficient.

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

Try to "clone" this Dir.

This is equivalent to self.sub_dir("."), but more efficient.

pub fn self_metadata(&self) -> Result<Metadata>

Retrieve metadata of this directory.

This is equivalent to self.metadata(".", LookupFlags::empty()), but it's significantly more efficient.

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

Retrieve information on the file with the given path.

The specified file must be located within this directory. Symlinks in the final component of the path are not followed.

pub fn recover_path(&self) -> Result<PathBuf>

Recover the path to the directory that this Dir is currently open to.

WARNINGS (make sure to read):

• Do NOT use this path to open any files within the directory (i.e. File::open(path.join("file.txt"))! That would defeat the entire purpose of this crate by opening vectors for symlink attacks.
• If a potentially malicious user controls a parent directory of the directory that this Dir is currently open to, the path returned by this function is NOT safe to use.

OS-specific optimizations:

• On Linux, this will try readlink("/proc/self/fd/$fd").
• On macOS, this will try fcntl(fd, F_GETPATH).

If either of these techniques fails (or on other platforms), it will fall back on a more reliable (but slower) strategy.

Some notes:

• If the directory has been deleted, this function will fail with ENOENT (this is guaranteed, though beware of race conditions).
• This function may or may not fail with EACCES if the currrent process does not have access to one or more of this directory's parent directories.

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

Set this process's current working directory to this directory.

This is roughly equivalent to std::env::set_current_dir(self.recover_path()?), but 1) it is much more efficient, and 2) it is more secure (notably, it avoids race conditions).

pub fn open_file(&self) -> OpenOptions<'_>

Return an OpenOptions struct that can be use to open files within this directory.

See the documentation of OpenOptions for more details.

Trait Implementations

impl AsRawFd for Dir

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Dir

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

Formats the value using the given formatter.

impl Drop for Dir

fn drop(&mut self)

Executes the destructor for this type.

impl FromRawFd for Dir

unsafe fn from_raw_fd(fd: RawFd) -> Self

Constructs a new instance of Self from the given raw file descriptor.

impl IntoRawFd for Dir

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.