More functionality dealing with UNIX file permissions for Rust
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Avril a1dfcce8f1
generalised fchmod
4 years ago
src generalised fchmod 4 years ago
.gitignore initial commit 4 years ago
Cargo.toml generalised fchmod 4 years ago
README.md Add README 4 years ago
build.rs initial commit 4 years ago

README.md

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

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

Creating through builder-pattern

You can add masks with add_mask()

let perms = Permissions::new()
	.add_mask(User::Owner, Bit::Read | Bit::Write)
	.add_mask(User::Group, Bit::Read);

And remove them with remove_mask()

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().

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.

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.

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);
}

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