Struct pathrs::Root

pub struct Root {
    pub resolver: Resolver,
    // some fields omitted
}

A handle to the root of a directory tree.

Safety

At the time of writing, it is considered a very bad idea to open a Root inside a possibly-attacker-controlled directory tree. While we do have protections that should defend against it (for both drivers), it's far more dangerous than just opening a directory tree which is not inside a potentially-untrusted directory.

Errors

If at any point an attack is detected during the execution of a Root method, an error will be returned. The method of attack detection is multi-layered and operates through explicit /proc/self/fd checks as well as (in the case of the native backend) kernel-space checks that will trigger -EXDEV in certain attack scenarios.

Additionally, if this root directory is moved then any subsequent operations will fail with an Error::SafetyViolation since it's not obvious whether there is an attacker or if the path was moved innocently. This restriction might be relaxed in the future.

Fields

resolver: Resolver

The underlying Resolver to use for all operations underneath this root. This affects not just Root::resolve but also all other methods which have to implicitly resolve a path underneath Root.

Methods

impl Root

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self, Error>

Open a Root handle.

The Resolver used by this handle is chosen at runtime based on which resolvers are supported by the running kernel (the default Resolver is always Resolver::default()). You can change the Resolver used by changing Root.resolver, though this is not recommended.

Errors

path must be an existing directory, and must (at the moment) be a fully-resolved pathname with no symlink components. This restriction might be relaxed in the future.

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

Create a copy of an existing Root.

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

pub fn into_file(self) -> File

Unwrap a Root to reveal the underlying File.

pub fn from_file_unchecked(inner: File) -> Self

Wrap a File into a Root.

The configuration is set to the system default and should be configured prior to usage, if appropriate.

Safety

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

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 resolve<P: AsRef<Path>>(&self, path: P) -> Result<Handle, Error>

Within the given Root's tree, resolve path and return a Handle. All symlink path components are scoped to Root.

Errors

If path doesn't exist, or an attack was detected during resolution, a corresponding Error will be returned. If no error is returned, then the path is guaranteed to have been reachable from the root of the directory tree and thus have been inside the root at one point in the resolution.

pub fn create<P: AsRef<Path>>(
    &self,
    path: P,
    inode_type: &InodeType
) -> Result<(), Error>

Within the Root's tree, create an inode at path as specified by inode_type.

Errors

If the path already exists (regardless of the type of the existing inode), an error is returned.

pub fn create_file<P: AsRef<Path>>(
    &self,
    path: P,
    perm: &Permissions
) -> Result<Handle, Error>

Create an InodeType::File within the Root's tree at path with the mode given by perm, and return a Handle to the newly-created file.

However, unlike the trivial way of doing the above:

root.create(path, inode_type)?;
// What happens if the file is replaced here!?
let handle = root.resolve(path, perm)?;

Root::create_file guarantees that the returned Handle is the same as the file created by the operation. This is only possible to guarantee for ordinary files because there is no O_CREAT-equivalent for other inode types.

Errors

Identical to Root::create.

pub fn remove<P: AsRef<Path>>(&self, path: P) -> Result<(), Error>

Within the Root's tree, remove the inode at path.

Any existing Handles to path will continue to work as before, since Linux does not invalidate file handles to unlinked files (though, directory handling is not as simple).

Errors

If the path does not exist or is a non-empty directory, an error will be returned. In order to remove a non-empty directory, please use Root::remove_all.

pub fn rename<P: AsRef<Path>>(
    &self,
    source: P,
    destination: P,
    flags: RenameFlags
) -> Result<(), Error>

Within the Root's tree, perform a rename with the given source and directory. The flags argument is passed directly to renameat2(2).

Errors

The error rules are identical to renameat2(2).

Trait Implementations

impl Debug for Root

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

Formats the value using the given formatter.