Struct pathrs::Handle

pub struct Handle { /* fields omitted */ }

A handle to an existing inode within a Root.

This handle references an already-resolved path which can be used for the purpose of "re-opening" the handle and get an actual File which can be used for ordinary operations.

Safety

It is critical for the safety of this library that at no point do you use interfaces like libc::openat directly on any RawFds you might extract from the File you get from this Handle. You must always do operations through a valid Root.

Methods

impl Handle

pub fn reopen<F: Into<OpenFlags>>(&self, flags: F) -> Result<File, Error>

"Upgrade" the handle to a usable File handle.

This new File handle is suitable for reading and writing. This does not consume the original handle (allowing for it to be used many times).

The File handle will be opened with O_NOCTTY and O_CLOEXEC set, regardless of whether those flags are present in the flags argument. You can correct these yourself if these defaults are not ideal for you:

1. fcntl(fd, F_SETFD, 0) will let you unset O_CLOEXEC.
2. ioctl(fd, TIOCSCTTY, 0) will set the fd as the controlling terminal (if you don't have one already, and the fd references a TTY).

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

Create a copy of an existing Handle.

The new handle is completely independent from the original, but references the same underlying file.

pub fn into_file(self) -> File

Unwrap a Handle to reveal the underlying File.

pub fn from_file_unchecked(inner: File) -> Self

Wrap a File into a Handle.

Safety

The caller guarantees that the provided file is an O_PATH file descriptor with exactly the same semantics as one created through Root::resolve. This means that this function should usually be used to convert a File returned from Handle::into_file (possibly from another process) into a Handle.

While this function is not marked as unsafe (because the safety guarantee required is not related to memory-safety), users should still take great care when using this method because it can cause other kinds of unsafety.

Trait Implementations

impl Debug for Handle

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

Formats the value using the given formatter.