Struct openat_ct::Dir

pub struct Dir(_);

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 flags() -> DirFlags

Create a flags builder for Dir objects. Initial flags default to `O_CLOEXEC’. More flags can be set added by ‘with()’ and existing/default flags can be removed by ‘without()’. The flags builder can the be used to ‘open()’ to create a Dir handle.

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

Open a directory descriptor at specified path with O_PATH when available. A descriptor obtained with this flag is restricted to do only certain operations:

• It may be used as anchor for opening sub-objects
• One can query metadata of this directory

This handle is not suitable for a ‘Dir::list()’ call and may yield a runtime error. Use ‘Dir::flags().open()’ to get a handle without O_PATH defined or use ‘Dir::list_self()’ which clone-upgrades the handle it used for the iteration.

pub fn is_dir(&self) -> bool

Checks if the fd associated with the Dir object is really a directory. There are subtle differences in how directories can be opened and what properties the resulting file handles have. On some platforms it is possible that Dir::open(“somefile”) succeeds. This will usually raise errors later when one tries to do Directory operations on this. While checking if such an handle comes with cost of a potential expensive ‘stat()’ operation. This library makes the assumption that in the ‘usual’ case Dir objects are only created on directories and operations on Dir handles handle errors properly. Still in some cases one may check a freshly created handle explicitly. Thats what ‘is_dir()’ is for. Returns ‘true’ when the underlying handles represents a directory and false otherwise.

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

List subdirectory of this dir

You can list directory itself with list_self.

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

List this dir

pub fn list(self) -> Result<DirIter>

Create a DirIter from a Dir Dir must not be a handle opened with O_PATH.

pub fn with<'a>(&'a self, flags: c_int) -> DirMethodFlags<'a>

Create a flags builder for member methods. Defaults to O_CLOEXEC | O_NOFOLLOW plus the given flags. Further flags can be added/removed by the ‘with()’/‘without()’ members. And finally be used by ‘sub_dir()’ and the different ‘open()’ calls.

pub fn without<'a>(&'a self, flags: c_int) -> DirMethodFlags<'a>

Create a flags builder for member methods. Defaults to O_CLOEXEC | O_NOFOLLOW with the given flags (which may O_CLOEXEC or O_NOFOLLOW) removed. Further flags can be added/removed by the ‘with()’/‘without()’ members. And finally be used by ‘sub_dir()’ and the different ‘open()’ calls.

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

Open subdirectory with O_PATH when available. A descriptor obtained with this flag is restricted to do only certain operations:

• It may be used as anchor for opening sub-objects
• One can query metadata of this directory

This handle is not suitable for a ‘Dir::list()’ call and may yield a runtime error. Use ‘Dir::with(0).sub_dir()’ to get a handle without O_PATH defined or use ‘Dir::list_dir()’ which clone-upgrades the handle it used for the iteration.

Note that this method does not resolve symlinks by default, so you may have to call read_link to resolve the real path first or create a handle ‘without(libc::O_NOFOLLOW)’.

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

Note that this method does not resolve symlinks by default, so you may have to call read_link to resolve the real path first.

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

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

If there exists a symlink at the destination path, this method will fail. In that case, you will need to remove the symlink before calling this method. If you are on Linux, you can alternatively create an unnamed file with new_unnamed_file and then rename it, clobbering the symlink at the destination.

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

Open file for append, create if necessary

If there exists a symlink at the destination path, this method will fail. In that case, you will need to call read_link to resolve the real path first.

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

If there exists a symlink at the destination path, this method will fail. In that case, you will need to remove the symlink before calling this method. If you are on Linux, you can alternatively create an unnamed file with new_unnamed_file and then rename it, clobbering the symlink at the destination.

pub fn new_unnamed_file(&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.

WARNING! On glibc < 2.22 file permissions of the newly created file may be arbitrary. Consider chowning after creating a file.

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

If there exists a symlink at the destination path, this method will fail. In that case, you will need to call read_link to resolve the real path first.

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 local_exchange<P: AsPath, R: AsPath>(&self, old: P, new: R) -> Result<()>

Similar to local_rename but atomically swaps both paths

Only supported on Linux.

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

If the destination path is a symlink, this will return the metadata of the symlink itself. If you would like to follow the symlink and return the metadata of the target, you will have to call read_link to resolve the real path first.

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

Returns the metadata of the directory itself.

pub unsafe fn from_raw_fd_checked(fd: RawFd) -> Result<Self>

Constructs a new Dir from a given raw file descriptor, ensuring it is a directory file descriptor first.

This function consumes ownership of the specified file descriptor. The returned Dir will take responsibility for closing it when it goes out of scope.

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

Creates a new independently owned handle to the underlying directory. The new handle has the same (Normal/O_PATH) semantics as the original handle.

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

Creates a new ‘Normal’ independently owned handle to the underlying directory.

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

Creates a new ‘O_PATH’ restricted independently owned handle to the underlying 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

The user must guarantee that the passed in RawFd is in fact a directory file descriptor.

impl IntoRawFd for Dir

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.