Struct Handle

pub struct Handle { /* private fields */ }

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 the OwnedFd you can extract from this Handle. You must always do operations through a valid Root.

Implementations

impl Handle

pub fn from_fd_unchecked<Fd: Into<OwnedFd>>(fd: Fd) -> Self

Wrap an OwnedFd 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 an OwnedFd returned from OwnedFd::from (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.

pub fn as_ref(&self) -> HandleRef<'_>

Borrow this Handle as a HandleRef.

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

Trait Implementations

impl AsFd for Handle

fn as_fd(&self) -> BorrowedFd<'_>

Access the underlying file descriptor for a Handle.

Note: This method is primarily intended to allow for tests and other code to check the status of the underlying OwnedFd without having to use OwnedFd::from. It is not safe to use this BorrowedFd directly to do filesystem operations. Please use the provided HandleRef methods.

impl Debug for Handle

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

Formats the value using the given formatter.

impl From<Handle> for OwnedFd

fn from(handle: Handle) -> Self

Unwrap a Handle to reveal the underlying OwnedFd.

Note: This method is primarily intended to allow for file descriptor passing or otherwise transmitting file descriptor information. If you want to get a File handle for general use, please use Handle::reopen instead.