Unix permissions symbolic notation

Cargo.toml

@@ -25,6 +25,7 @@ path = "src/main.rs"
 
 [dependencies]
 ansi_term = "0.12.1"
+chrono = "0.4.24"
 clap = { version = "4.1.1", features = ["derive"] }
 clap_complete = "4.1.1"
 filesize = "0.2.0"
@@ -36,6 +37,9 @@ once_cell = "1.17.0"
 regex = "1.7.3"
 thiserror = "1.0.40"
 
+[target.'cfg(unix)'.dependencies]
+libc = "0.2.141"
+
 [dev-dependencies]
 indoc = "2.0.0"
 strip-ansi-escapes = "0.1.1"

src/fs/inode.rs

@@ -1,7 +1,7 @@
 use std::{convert::TryFrom, fs::Metadata};
 
 /// Represents a file's underlying inode.
-#[derive(Debug, PartialEq, Eq, Hash)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub struct Inode {
  pub ino: u64,
  pub dev: u64,

src/fs/mod.rs

@@ -4,6 +4,14 @@ use std::{fs, path::PathBuf};
 /// Operations pertaining to underlying inodes of files.
 pub mod inode;
 
+/// Unix file permissions.
+#[cfg(unix)]
+pub mod permissions;
+
+#[cfg(unix)]
+/// Determining whether or not a file has extended attributes.
+pub mod xattr;
+
 /// Returns the path to the target of the soft link. Returns `None` if provided `dir_entry` isn't a
 /// symlink.
 pub fn symlink_target(dir_entry: &DirEntry) -> Option<PathBuf> {

src/fs/permissions/class.rs

@@ -0,0 +1,152 @@
+use std::fmt::{self, Display};
+
+/// The set of permissions for a particular class i.e. user, group, or other.
+#[derive(Debug)]
+#[allow(clippy::module_name_repetitions)]
+pub struct ClassPermissions {
+ class: Class,
+ attr: Option<Attribute>,
+ pub(super) triad: PermissionsTriad,
+}
+
+/// The class type that is associated with a permissions triad.
+#[derive(Debug)]
+pub enum Class {
+ User,
+ Group,
+ Other,
+}
+
+/// Represents the special attributes that exist on the overall file corresponding to the setuid,
+/// setgid, and the sticky bit.
+#[derive(Debug, PartialEq, Eq)]
+#[allow(clippy::upper_case_acronyms)]
+pub enum Attribute {
+ SUID,
+ SGID,
+ Sticky,
+}
+
+/// Read, write, execute permissions.
+#[derive(Debug, PartialEq, Eq)]
+pub enum PermissionsTriad {
+ Read,
+ Write,
+ Execute,
+ ReadWrite,
+ ReadExecute,
+ WriteExecute,
+ ReadWriteExecute,
+ None,
+}
+
+/// All `permissions_mask` arguments represents the bits of `st_mode` which excludes the file-type
+/// and the setuid, setgid, and sticky bit.
+impl ClassPermissions {
+ /// Computes user permissions.
+ pub fn user_permissions_from(st_mode: u32) -> Self {
+ let read = Self::enabled(st_mode, libc::S_IRUSR);
+ let write = Self::enabled(st_mode, libc::S_IWUSR);
+ let execute = Self::enabled(st_mode, libc::S_IXUSR);
+ let suid = Self::enabled(st_mode, libc::S_ISUID).then_some(Attribute::SUID);
+
+ Self::permissions_from_rwx(Class::User, read, write, execute, suid)
+ }
+
+ /// Computes group permissions.
+ pub fn group_permissions_from(st_mode: u32) -> Self {
+ let read = Self::enabled(st_mode, libc::S_IRGRP);
+ let write = Self::enabled(st_mode, libc::S_IWGRP);
+ let execute = Self::enabled(st_mode, libc::S_IXGRP);
+ let sgid = Self::enabled(st_mode, libc::S_ISGID).then_some(Attribute::SGID);
+
+ Self::permissions_from_rwx(Class::Group, read, write, execute, sgid)
+ }
+
+ /// Computes other permissions.
+ pub fn other_permissions_from(st_mode: u32) -> Self {
+ let read = Self::enabled(st_mode, libc::S_IROTH);
+ let write = Self::enabled(st_mode, libc::S_IWOTH);
+ let execute = Self::enabled(st_mode, libc::S_IXOTH);
+ let sticky = Self::enabled(st_mode, libc::S_ISVTX).then_some(Attribute::Sticky);
+
+ Self::permissions_from_rwx(Class::Other, read, write, execute, sticky)
+ }
+
+ /// Checks if a particular mode (read, write, or execute) is enabled.
+ fn enabled<N>(st_mode: u32, mask: N) -> bool
+ where
+ N: Copy + Into<u32>,
+ {
+ st_mode & mask.into() == mask.into()
+ }
+
+ /// Returns `true` if sticky bit is enabled.
+ pub fn attr_is_sticky(&self) -> bool {
+ self.attr
+ .as_ref()
+ .map_or(false, |attr| attr == &Attribute::Sticky)
+ }
+
+ /// Helper function to compute permissions.
+ const fn permissions_from_rwx(
+ class: Class,
+ r: bool,
+ w: bool,
+ x: bool,
+ attr: Option<Attribute>,
+ ) -> Self {
+ let triad = match (r, w, x) {
+ (true, false, false) => PermissionsTriad::Read,
+ (false, true, false) => PermissionsTriad::Write,
+ (false, false, true) => PermissionsTriad::Execute,
+ (true, true, false) => PermissionsTriad::ReadWrite,
+ (true, false, true) => PermissionsTriad::ReadExecute,
+ (false, true, true) => PermissionsTriad::WriteExecute,
+ (true, true, true) => PermissionsTriad::ReadWriteExecute,
+ (false, false, false) => PermissionsTriad::None,
+ };
+
+ Self { class, attr, triad }
+ }
+}
+
+/// The symbolic representation of a [PermissionsTriad].
+impl Display for ClassPermissions {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ match self.class {
+ Class::Other if self.attr_is_sticky() => match self.triad {
+ PermissionsTriad::Read => write!(f, "r-T"),
+ PermissionsTriad::Write => write!(f, "-wT"),
+ PermissionsTriad::Execute => write!(f, "--t"),
+ PermissionsTriad::ReadWrite => write!(f, "rwT"),
+ PermissionsTriad::ReadExecute => write!(f, "r-t"),
+ PermissionsTriad::WriteExecute => write!(f, "-wt"),
+ PermissionsTriad::ReadWriteExecute => write!(f, "rwt"),
+ PermissionsTriad::None => write!(f, "--T"),
+ },
+
+ _ if self.attr.is_some() => match self.triad {
+ PermissionsTriad::Read => write!(f, "r-S"),
+ PermissionsTriad::Write => write!(f, "-wS"),
+ PermissionsTriad::Execute => write!(f, "--s"),
+ PermissionsTriad::ReadWrite => write!(f, "rwS"),
+ PermissionsTriad::ReadExecute => write!(f, "r-s"),
+ PermissionsTriad::WriteExecute => write!(f, "-ws"),
+ PermissionsTriad::ReadWriteExecute => write!(f, "rws"),
+ PermissionsTriad::None => write!(f, "--S"),
+ },
+
+ _ => match self.triad {
+ PermissionsTriad::Read => write!(f, "r--"),
+ PermissionsTriad::Write => write!(f, "-w-"),
+ PermissionsTriad::Execute => write!(f, "--x"),
+ PermissionsTriad::ReadWrite => write!(f, "rw-"),
+ PermissionsTriad::ReadExecute => write!(f, "r-x"),
+ PermissionsTriad::WriteExecute => write!(f, "-wx"),
+ PermissionsTriad::ReadWriteExecute => write!(f, "rwx"),
+ PermissionsTriad::None => write!(f, "---"),
+ },
+ }
+ }
+}

src/fs/permissions/error.rs

@@ -0,0 +1,7 @@
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum Error {
+ #[error("Encountered an unknown file type.")]
+ UnknownFileType,
+}

src/fs/permissions/file_type.rs

@@ -0,0 +1,55 @@
+use super::error::Error;
+
+/// Unix file types.
+#[derive(Debug, PartialEq, Eq)]
+pub enum FileType {
+ Directory,
+ File,
+ Symlink,
+ Fifo,
+ Socket,
+ CharDevice,
+ BlockDevice,
+}
+
+impl FileType {
+ /// Unix file identifiers that you'd find in the `ls -l` command.
+ pub const fn identifier(&self) -> char {
+ match self {
+ Self::Directory => 'd',
+ Self::File => '.',
+ Self::Symlink => 'l',
+ Self::Fifo => 'p',
+ Self::Socket => 's',
+ Self::CharDevice => 'c',
+ Self::BlockDevice => 'b',
+ }
+ }
+}
+
+/// The argument `mode` is meant to come from the `mode` method of [std::fs::Permissions].
+impl TryFrom<u32> for FileType {
+ type Error = Error;
+
+ fn try_from(mode: u32) -> Result<Self, Self::Error> {
+ let file_mask = mode & u32::from(libc::S_IFMT);
+
+ if file_mask == u32::from(libc::S_IFIFO) {
+ Ok(Self::Fifo)
+ } else if file_mask == u32::from(libc::S_IFCHR) {
+ Ok(Self::CharDevice)
+ } else if file_mask == u32::from(libc::S_IFDIR) {
+ Ok(Self::Directory)
+ } else if file_mask == u32::from(libc::S_IFBLK) {
+ Ok(Self::BlockDevice)
+ } else if file_mask == u32::from(libc::S_IFREG) {
+ Ok(Self::File)
+ } else if file_mask == u32::from(libc::S_IFLNK) {
+ Ok(Self::Symlink)
+ } else if file_mask == u32::from(libc::S_IFSOCK) {
+ Ok(Self::Socket)
+ } else {
+ Err(Error::UnknownFileType)
+ }
+ }
+}

src/fs/permissions/mod.rs

@@ -0,0 +1,126 @@
+use class::ClassPermissions;
+use error::Error;
+use file_type::FileType;
+use std::{
+ convert::TryFrom,
+ fmt::{self, Display, Octal},
+ os::unix::fs::PermissionsExt,
+};
+
+/// For working with permissions for a particular class i.e. user, group, or other.
+pub mod class;
+
+/// File permission related errors.
+pub mod error;
+
+/// For working with Unix file identifiers.
+pub mod file_type;
+
+#[cfg(test)]
+mod test;
+
+impl SymbolicNotation for std::fs::Permissions {}
+
+/// Trait that is used to extend [std::fs::Permissions] behavior such that it allows for `mode` to
+/// be expressed in Unix's symbolic notation for file permissions.
+pub trait SymbolicNotation: PermissionsExt {
+ /// Attempts to return a [FileMode] which implements [Display] allowing it to be presented in
+ /// symbolic notation for file permissions.
+ fn try_mode_symbolic_notation(&self) -> Result<FileMode, Error> {
+ let mode = self.mode();
+ FileMode::try_from(mode)
+ }
+}
+
+/// A struct which holds information about the permissions of a particular file. [FileMode]
+/// implements [Display] which allows it to be conveniently presented in symbolic notation when
+/// expressing file permissions.
+pub struct FileMode {
+ pub st_mode: u32,
+ file_type: FileType,
+ user_permissions: ClassPermissions,
+ group_permissions: ClassPermissions,
+ other_permissions: ClassPermissions,
+}
+
+impl FileMode {
+ /// Constructor for [FileMode].
+ pub const fn new(
+ st_mode: u32,
+ file_type: FileType,
+ user_permissions: ClassPermissions,
+ group_permissions: ClassPermissions,
+ other_permissions: ClassPermissions,
+ ) -> Self {
+ Self {
+ st_mode,
+ file_type,
+ user_permissions,
+ group_permissions,
+ other_permissions,
+ }
+ }
+
+ /// Returns a reference to `file_type`.
+ pub const fn file_type(&self) -> &FileType {
+ &self.file_type
+ }
+
+ /// Returns a reference to a [ClassPermissions] which represents the permissions of the user class.
+ pub const fn user_permissions(&self) -> &ClassPermissions {
+ &self.user_permissions
+ }
+
+ /// Returns a reference to a [ClassPermissions] which represents the permissions of the group class.
+ pub const fn group_permissions(&self) -> &ClassPermissions {
+ &self.group_permissions
+ }
+
+ /// Returns a reference to a [ClassPermissions] which represents the permissions of the other class.
+ pub const fn other_permissions(&self) -> &ClassPermissions {
+ &self.other_permissions
+ }
+}
+
+/// For representing [FileMode] in symbolic notation.
+impl Display for FileMode {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ let file_iden = self.file_type().identifier();
+ let user_permissions = self.user_permissions();
+ let group_permissions = self.group_permissions();
+ let other_permissions = self.other_permissions();
+
+ write!(
+ f,
+ "{file_iden}{user_permissions}{group_permissions}{other_permissions}"
+ )
+ }
+}
+
+/// For the octal representation of permissions
+impl Octal for FileMode {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ let modes_mask = self.st_mode & !u32::from(libc::S_IFMT);
+ fmt::Octal::fmt(&modes_mask, f)
+ }
+}
+
+/// The argument `st_mode` is meant to come from the `mode` method of [std::fs::Permissions].
+impl TryFrom<u32> for FileMode {
+ type Error = Error;
+
+ fn try_from(st_mode: u32) -> Result<Self, Self::Error> {
+ let file_type = FileType::try_from(st_mode)?;
+ let user_permissions = ClassPermissions::user_permissions_from(st_mode);
+ let group_permissions = ClassPermissions::group_permissions_from(st_mode);
+ let other_permissions = ClassPermissions::other_permissions_from(st_mode);
+
+ Ok(Self::new(
+ st_mode,
+ file_type,
+ user_permissions,
+ group_permissions,
+ other_permissions,
+ ))
+ }
+}