Crate file_mode

Decode Unix file mode bits, change them and apply them to files.

All file type, special and protection bits described in sys/stat.h are represented.

The Mode can represent a file mode partially by the use of a bitmask. Only modified bits will be changed in the target file. Modifications specific only to directories (search) are handled correctly.

Usage examples

Decoding mode bits

use std::path::Path;
use file_mode::{ModePath, User};

let mode = Path::new("LICENSE").mode().unwrap();

assert!(mode.file_type().unwrap().is_regular_file());
assert!(mode.user_protection(User::Owner).is_read_set());
assert!(mode.user_protection(User::Group).is_write_set());
assert!(!mode.user_protection(User::Other).is_execute_set());

Applying chmod strings

use std::path::Path;
use file_mode::ModePath;

Path::new("LICENSE").set_mode("u+r,g+u").unwrap();

Applying octal modes

use std::path::Path;
use file_mode::ModePath;

Path::new("LICENSE").set_mode(0o664).unwrap();

Printing standard mode strings

use std::path::Path;
use file_mode::ModePath;

let mode = Path::new("LICENSE").mode().unwrap();

println!("{}", mode); // -rw-rw-r--
assert_eq!(&mode.to_string(), "-rw-rw-r--");

Constructing Mode programmatically

use file_mode::{Mode, Protection, ProtectionBit, User};

let mut mode = Mode::empty();
let mut rw = Protection::empty();

rw.set(ProtectionBit::Read);
rw.set(ProtectionBit::Write);

mode.set_protection(User::Owner, &rw);
mode.set_protection(User::Group, &rw);
mode.set_protection(User::Other, &ProtectionBit::Read.into());

assert_eq!(mode.mode(), 0o664);

mode.set_mode_path("LICENSE").unwrap();

For non-Unix systems mode can still be used but not set to files

use file_mode::{Mode, Protection, ProtectionBit, User};

let mut mode = Mode::empty();
let mut rw = Protection::empty();

rw.set(ProtectionBit::Read);
rw.set(ProtectionBit::Write);

mode.set_protection(User::Owner, &rw);
mode.set_protection(User::Group, &rw);
mode.set_protection(User::Other, &ProtectionBit::Read.into());

assert_eq!(mode.apply_to(0o600), 0o664);

Use Mode::from to construct mode as if it was read from a file:

use file_mode::Mode;

let mut mode = Mode::from(0o600);

mode.set_str("g+rw,o+r").unwrap();

assert_eq!(mode.mode(), 0o664);

Features and platform support

This carte should compile on all platforms. On non-Unix (not target_family = "unix") systems, functions related to setting mode to files will not be available.

The calling process’s umask

On non-Unix systems, the calling process’s umask is emulated via global variable and defaults to 0o002.

Serde

Implementations of Serialize and Deserialize for Mode can be enabled with serde feature flag.

Structs

Mode	Unix file mode.
Protection	Protection bits for user’s access to a file.
Special	Special bits set on a file.

Enums

FileType	Type of the file as encoded in the mode value.
ModeParseError	Error parsing mode string.
ProtectionBit	Protection bit that can be set for a User.
SpecialBit	Special bit that can be set for a User.
User	Represents which user’s access to the file will be changed.

Functions

set_umask	Sets the calling process’s umask.
umask	Gets the calling process’s umask.