openat/
lib.rs

Help
1//! # Handling Files Relative to File Descriptor
2//!
3//! Main concept here is a `Dir` which holds `O_PATH` file descriptor, you
4//! can create it with:
5//!
6//! * `Dir::open("/some/path")` -- open this directory as a file descriptor
7//! * `Dir::from_raw_fd(fd)` -- uses a file descriptor provided elsewhere
8//!
9//! *Note after opening file descriptors refer to same directory regardless of
10//! where it's moved or mounted (with `pivot_root` or `mount --move`). It may
11//! also be unmounted or be out of chroot and you will still be able to
12//! access files relative to it.*
13//!
14//! *Note2: The constructor `Dir::cwd()` is deprecated, and it's recommended
15//! to use `Dir::open(".")` instead.*
16//!
17//! Most other operations are done on `Dir` object and are executed relative
18//! to it:
19//!
20//! * `Dir::list_dir()`
21//! * `Dir::sub_dir()`
22//! * `Dir::read_link()`
23//! * `Dir::open_file()`
24//! * `Dir::create_file()`
25//! * `Dir::update_file()`
26//! * `Dir::create_dir()`
27//! * `Dir::symlink()`
28//! * `Dir::local_rename()`
29//!
30//! Functions that expect path relative to the directory accept both the
31//! traditional path-like objects, such as Path, PathBuf and &str, and
32//! `Entry` type returned from `list_dir()`. The latter is faster as underlying
33//! system call wants `CString` and we keep that in entry.
34//!
35//! Note that if path supplied to any method of dir is absolute the Dir file
36//! descriptor is ignored.
37//!
38//! Also while all methods of dir accept any path if you want to prevent
39//! certain symlink attacks and race condition you should only use
40//! a single-component path. I.e. open one part of a chain at a time.
41//!
42#![warn(missing_docs)]
43
44extern crate libc;
45
46mod dir;
47mod list;
48mod name;
49mod filetype;
50mod metadata;
51
52pub use list::DirIter;
53pub use name::AsPath;
54pub use dir::{rename, hardlink};
55pub use filetype::SimpleType;
56pub use metadata::Metadata;
57
58use std::ffi::CString;
59use std::os::unix::io::RawFd;
60
61/// A safe wrapper around directory file descriptor
62///
63/// Construct it either with ``Dir::cwd()`` or ``Dir::open(path)``
64///
65#[derive(Debug)]
66pub struct Dir(RawFd);
67
68/// Entry returned by iterating over `DirIter` iterator
69#[derive(Debug)]
70pub struct Entry {
71    name: CString,
72    file_type: Option<SimpleType>,
73}
74
75#[cfg(test)]
76mod test {
77    use std::mem;
78    use super::Dir;
79
80    fn assert_sync<T: Sync>(x: T) -> T { x }
81    fn assert_send<T: Send>(x: T) -> T { x }
82
83    #[test]
84    fn test() {
85        let d = Dir(3);
86        let d = assert_sync(d);
87        let d = assert_send(d);
88        // don't execute close for our fake RawFd
89        mem::forget(d);
90    }
91}
92
openat/lib.rs

openat/
lib.rs
