Crate file_mode

Crate file_mode 

Source
Expand description

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.
ModeError
Error setting mode to a file.
ModeParseError
Error parsing mode string.
ProtectionBit
Protection bit that can be set for a User.
SetMode
Types that convert to this type can be used with set_mode methods.
SpecialBit
Special bit that can be set for a User.
User
Represents which user’s access to the file will be changed.

Traits§

ModeFile
Extension methods for File.
ModePath
Extension methods for objects that can reference as Path.

Functions§

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