posix_acl/lib.rs
1//! **posix-acl** is a Rust library to interact with POSIX file system Access Control Lists (ACL).
2//! It wraps the operating system's C interface with a safe Rust API. The API is deliberately
3//! different from the POSIX C API to make it easier to use.
4//!
5//! NB! Currently only tested on Linux.
6//!
7//! While officially called a "list", The main struct [`PosixACL`] implements a "mapping-like"
8//! interface where key is the [`Qualifier`] enum and value is `u32` containing permission bits.
9//! This is without any loss of functionality, as duplicate entries with the same Qualifier are
10//! disallowed by POSIX anyway.
11//!
12//! For background information about ACL behavior, read [POSIX Access Control Lists on Linux](
13//! https://www.usenix.org/legacy/publications/library/proceedings/usenix03/tech/freenix03/full_papers/gruenbacher/gruenbacher_html/main.html).
14//!
15//! ## Usage example
16//! ```
17//! use posix_acl::{PosixACL, Qualifier, ACL_READ, ACL_WRITE};
18//!
19//! # std::fs::File::create("/tmp/posix-acl-testfile").unwrap();
20//! // Read ACL from file (if there is no ACL yet, the OS will synthesize one)
21//! let mut acl = PosixACL::read_acl("/tmp/posix-acl-testfile").unwrap();
22//!
23//! // Get permissions of owning user of the file
24//! let perm = acl.get(Qualifier::UserObj).unwrap();
25//! assert_eq!(perm, ACL_READ | ACL_WRITE);
26//!
27//! // Get permissions for user UID 1234
28//! let perm = acl.get(Qualifier::User(1234));
29//! assert!(perm.is_none());
30//!
31//! // Grant read access to group GID 1234 (adds new entry or overwrites an existing entry)
32//! acl.set(Qualifier::Group(1234), ACL_READ);
33//!
34//! // Remove ACL entry of group GID 1234
35//! acl.remove(Qualifier::Group(1234));
36//!
37//! // Write ACL back to the file
38//! acl.write_acl("/tmp/posix-acl-testfile").unwrap();
39//! ```
40
41#![warn(clippy::pedantic)]
42
43mod acl;
44mod entry;
45mod error;
46mod iter;
47mod util;
48
49/// Read permission
50pub const ACL_READ: u32 = acl_sys::ACL_READ;
51/// Write permission
52pub const ACL_WRITE: u32 = acl_sys::ACL_WRITE;
53/// Execute permission
54pub const ACL_EXECUTE: u32 = acl_sys::ACL_EXECUTE;
55/// All possible permissions combined: `ACL_READ | ACL_WRITE | ACL_EXECUTE`
56pub const ACL_RWX: u32 = ACL_READ | ACL_WRITE | ACL_EXECUTE;
57
58// Re-export public structs
59pub use acl::PosixACL;
60pub use entry::ACLEntry;
61pub use entry::Qualifier;
62pub use error::ACLError;