Crate file_mode

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.

Crate file_modeCopy item path