Readable Unix Permissions

Data types for the UNIX file permissions model. Convertable to and from mode_t.

Usage

Crate is designed to give finer and more sane control over mode_t, so there are multiple ways of using the Permissions struct.

All the below functions are const fn on nightly.

Creating from mode

rust let perms = Permissions::from_mask(0o644); // Any value above 0u777 is truncated.

Creating through builder-pattern

You can add masks with add_mask() rust let perms = Permissions::new() .add_mask(User::Owner, Bit::Read | Bit::Write) .add_mask(User::Group, Bit::Read); And remove them with remove_mask()

rust let perms = Permissions::from_mask(0o777) .remove_mask(User::Other, Bit::Write | Bit::Execute) .remove_mask(User::Group, Bit::Write);

Checking

You can check which modes are set with has_mask().

rust let perms = Permissions::from_mask(0o754); assert!(perms.has_mask(User::Owner, Bit::Mask)); assert!(perms.has_mask(User::Group, Bit::Read | Bit::Execute)); assert!(perms.has_mask(User::Other, Bit::Read));

We also derive PartialEq<u32>, to compare with mode_t directly.

``` rust let perms = Permissions::from_mask(0o644);

assert_eq!(perms, 0o644); ```

Extension trait

We also define an extension trait on target family unix that follows std::os::unix::fs::PermissionsExt. See [ext.rs] for details.

``` rust use readable_perms::PermissionsExt as UnixPermsExt; use std::os::unix::fs::PermissionsExt;

fn do_thing(file: &mut std::fs::File) { let perms = file.metadata().unwrap().permissions().unix(); println!("Perms are {}", perms); } ```

Modifying permissions

With default feature chmod enabled, also define extension traits for modifying permissions on types that implement AsRawFd (like std::fs::File), and AsRef<Path>.

``` rust use readable_perms::{FChmodExt,ChmodExt};

fn modpath>(path: P) { path.chmod(Permissions::frommask(0o644)).expect("Uh oh") }

fn modfile(file: &mut std::fs::File) { file.chmod(Permissinos::frommask(0u777)).expect("Uh oh") } ```

Performance

On nightly, most functions are const fn incuring no runtime cost for constant definitions. On stable, not so. Either way, we define a global const lookup table, so that conversions are as fast as a memory lookup.

Adding and removing the masks is usually 1 or two bitwise operations. TODO: Benchmark these?

Benchmarks

| Type | Value | |-----------------------|----------------------| | Conversions from mode | 159 ns/iter (+/- 15) | | Conversions to mode | 162 ns/iter (+/- 15) |

License

GPL'd with <3