Struct openat::Dir

source ·
pub struct Dir(/* private fields */);
Expand description

A safe wrapper around directory file descriptor

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

Implementations§

source§

impl Dir

source

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)

source

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

Open a directory descriptor at specified path

source

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.

source

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

Open subdirectory

Read link in this directory

source

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

Open file for reading in this directory

source

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

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

source

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

Open file for append, create if necessary

source

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

source

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.

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.

source

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.

source

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

Make a symlink in this directory

Note: the order of arguments differ from symlinkat

source

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

Create a subdirectory in this directory

source

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)

source

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

Remove a subdirectory in this directory

Note only empty directory may be removed

source

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

Remove a file in this directory

source

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.

source

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

Returns metadata of an entry in this directory

Trait Implementations§

source§

impl AsRawFd for Dir

source§

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor. Read more
source§

impl Debug for Dir

source§

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

Formats the value using the given formatter. Read more
source§

impl Drop for Dir

source§

fn drop(&mut self)

Executes the destructor for this type. Read more
source§

impl FromRawFd for Dir

source§

unsafe fn from_raw_fd(fd: RawFd) -> Dir

Constructs a new instance of Self from the given raw file descriptor. Read more
source§

impl IntoRawFd for Dir

source§

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor. Read more

Auto Trait Implementations§

§

impl RefUnwindSafe for Dir

§

impl Send for Dir

§

impl Sync for Dir

§

impl Unpin for Dir

§

impl UnwindSafe for Dir

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.