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§

Functions§

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