Struct Dir

pub struct Dir(/* private fields */);

A safe wrapper around directory file descriptor

Construct it either with Dir::cwd() or Dir::open(path)

Implementations

impl Dir

pub fn cwd() -> Dir

👎Deprecated since 0.1.15: Use Dir::open(".") instead. Dir::cwd() doesn’t open actual file descriptor and uses magic value instead which resolves to current dir on any syscall invocation. This is usually counter-intuitive and yields a broken file descriptor when using Dir::as_raw_fd. Will be removed in version v0.2 of the library.

Creates a directory descriptor that resolves paths relative to current working directory (AT_FDCWD)

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

Open a directory descriptor at specified path

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

List subdirectory of this dir

You can list directory itself if "." is specified as path.

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

Open subdirectory

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

Read link in this directory

pub fn open_file<P: AsPath>(&self, path: P) -> Result<File>

Open file for reading in this directory

pub fn write_file<P: AsPath>(&self, path: P, mode: mode_t) -> Result<File>

Open file for writing, create if necessary, truncate on open

pub fn append_file<P: AsPath>(&self, path: P, mode: mode_t) -> Result<File>

Open file for append, create if necessary

pub fn create_file<P: AsPath>(&self, path: P, mode: mode_t) -> Result<File>

👎Deprecated since 0.1.7: please use write_file instead

Create file for writing (and truncate) in this directory

Deprecated alias for write_file

pub fn new_unnamed_file<P: AsPath>(&self, _mode: mode_t) -> Result<File>

Create a tmpfile in this directory which isn’t linked to any filename

This works by passing O_TMPFILE into the openat call. The flag is supported only on linux. So this function always returns error on such systems.

Note: It may be unclear why creating unnamed file requires a dir. There are two reasons:

1. It’s created (and occupies space) on a real filesystem, so the directory is a way to find out which filesystem to attach file to
2. This method is mostly needed to initialize the file then link it using link_file_at to the real directory entry. When linking it must be linked into the same filesystem. But because for most programs finding out filesystem layout is an overkill the rule of thumb is to create a file in the the target directory.

Currently, we recommend to fallback on any error if this operation can’t be accomplished rather than relying on specific error codes, because semantics of errors are very ugly.

pub fn link_file_at<F: AsRawFd, P: AsPath>( &self, _file: F, _path: P, ) -> Result<()>

Link open file to a specified path

This is used with new_unnamed_file() to create and initialize the file before linking it into a filesystem. This requires /proc to be mounted and works only on linux.

On systems other than linux this always returns error. It’s expected that in most cases this methos is not called if new_unnamed_file fails. But in obscure scenarios where /proc is not mounted this method may fail even on linux. So your code should be able to fallback to a named file if this method fails too.

pub fn new_file<P: AsPath>(&self, path: P, mode: mode_t) -> Result<File>

Create file if not exists, fail if exists

This function checks existence and creates file atomically with respect to other threads and processes.

Technically it means passing O_EXCL flag to open.

pub fn update_file<P: AsPath>(&self, path: P, mode: mode_t) -> Result<File>

Open file for reading and writing without truncation, create if needed

pub fn symlink<P: AsPath, R: AsPath>(&self, path: P, value: R) -> Result<()>

Make a symlink in this directory

Note: the order of arguments differ from symlinkat

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

Create a subdirectory in this directory

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

Rename a file in this directory to another name (keeping same dir)

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

Remove a subdirectory in this directory

Note only empty directory may be removed

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

Remove a file in this directory

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

Get the path of this directory (if possible)

This uses symlinks in /proc/self, they sometimes may not be available so use with care.

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

Returns metadata of an entry in this directory

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) -> Dir

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.