Crate openat_ct[−][src]
Expand description
Handling Files Relative to File Descriptor
Main concept here is a Dir which holds O_PATH file descriptor, you
can create it with:
Dir::open("/some/path")– open this directory as a file descriptorDir::from_raw_fd(fd)– uses a file descriptor provided elsewhere
Note after opening file descriptors refer to same directory regardless of
where it’s moved or mounted (with pivot_root or mount --move). It may
also be unmounted or be out of chroot and you will still be able to
access files relative to it.
Note2: The constructor Dir::cwd() is deprecated, and it’s recommended
to use Dir::open(".") instead.
Note3: Some OS’s (e.g., macOS) do not provide O_PATH, in which case the
file descriptor is of regular type.
Most other operations are done on Dir object and are executed relative
to it:
Dir::list_dir()Dir::sub_dir()Dir::read_link()Dir::open_file()Dir::create_file()Dir::update_file()Dir::create_dir()Dir::symlink()Dir::local_rename()
Functions that expect path relative to the directory accept both the
traditional path-like objects, such as Path, PathBuf and &str, and
Entry type returned from list_dir(). The latter is faster as underlying
system call wants CString and we keep that in entry.
Note that if path supplied to any method of dir is absolute the Dir file descriptor is ignored.
Also while all methods of dir accept any path if you want to prevent certain symlink attacks and race condition you should only use a single-component path. I.e. open one part of a chain at a time.
Structs
A safe wrapper around directory file descriptor
‘Dir::new()’ creates a new DirFlags object with default (O_CLOEXEC) flags. One can then freely add/remove flags to the set. The final open calls will add O_DIRECTORY and O_PATH as applicable/supported but not verify or remove any defined flags. This allows passing flags the ‘openat’ implementation is not even aware about. Thus the open call may fail with some error when one constructed an invalid flag set.
Iterator over directory entries
‘Dir::with(&self)’/‘Dir::with(&self)’ creates a new DirMethodsFlags object with default (O_CLOEXEC|O_NOFOLLOW) flags. One can then freely add/remove flags to the set. Implements proxies for the Dir:: methods that open contained objects.
Entry returned by iterating over DirIter iterator
A file metadata
Enums
This is a simplified file type enum that is easy to match
Constants
Value if the libc::O_DIRECTORY flag when supported by the system, otherwise 0
Value if the libc::O_PATH flag when supported by the system, otherwise 0
Value if the libc::O_SEARCH flag when supported by the system, otherwise 0
Traits
The purpose of this is similar to AsRef<Path> but it’s optimized for
things that can be directly used as CStr (which is type passed to
the underlying system call).