cap_std/fs/mod.rs
1//! A capability-based filesystem API modeled after [`std::fs`].
2//!
3//! This corresponds to [`std::fs`].
4//!
5//! Instead of [`std::fs`'s free functions] and [`std::fs::File`]'s
6//! constructors which operate on bare paths, this crate has methods on [`Dir`]
7//! which operate on paths which must be relative to the directory.
8//!
9//! Where `std` says "the filesystem", this API says "a filesystem", as
10//! it doesn't assume that there's a single global filesystem namespace.
11//!
12//! Since all functions which expose raw file descriptors are `unsafe`,
13//! I/O handles in this API are unforgeable (unsafe code notwithstanding).
14//! This combined with a lack of absolute paths provides a natural
15//! capability-based interface.
16//!
17//! This crate uses the existing `std::path::Path` rather than having its own
18//! path type, however while `std::path::Path` is mostly just a pure datatype,
19//! it includes aliases for several `std::fs` functions. To preserve the
20//! capability-based interface, avoid using `std::path::Path`'s `canonicalize`,
21//! `read_link`, `read_dir`, `metadata`, and `symlink_metadata` functions.
22//!
23//! [`std::fs`'s free functions]: https://doc.rust-lang.org/std/fs/#functions
24
25mod dir;
26mod dir_entry;
27mod file;
28mod read_dir;
29
30pub use dir::Dir;
31pub use dir_entry::DirEntry;
32pub use file::File;
33pub use read_dir::ReadDir;
34
35// Re-export types from `cap_primitives`.
36pub use cap_primitives::fs::{DirBuilder, FileType, Metadata, OpenOptions, Permissions};
37
38// Re-export conditional types from `cap_primitives`.
39#[cfg(any(unix, target_os = "vxworks", all(windows, windows_file_type_ext)))]
40pub use cap_primitives::fs::FileTypeExt;
41#[cfg(unix)]
42pub use cap_primitives::fs::{DirBuilderExt, PermissionsExt};
43pub use cap_primitives::fs::{FileExt, MetadataExt, OpenOptionsExt};