Merge pull request #7 from jcaesar/enh

Enums for testing permissions and matching file type

Author: sourcefrog

src/lib.rs

@@ -43,14 +43,92 @@ fn type_bits(mode: u32) -> u32 {
     (mode >> 12) & 0o17
 }
 
+/// The different types of files known to this library
+///
+/// Can be constructed `From<u32>`.
+/// ```
+/// assert_eq!(unix_mode::Type::from(0o0100640), unix_mode::Type::File);
+/// ```
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+#[non_exhaustive]
+pub enum Type {
+    File,
+    Dir,
+    Symlink,
+    Socket,
+    Fifo,
+    BlockDevice,
+    CharDevice,
+    /// Removed file in union filesystems
+    Whiteout,
+    /// File type not recognized by this version of this library
+    ///
+    /// More types might be added in the future, so the semantics of this variant may change.
+    Unknown,
+}
+
+impl From<u32> for Type {
+    /// Parse type from mode
+    ///
+    fn from(mode: u32) -> Type {
+        use Type::*;
+        match type_bits(mode) {
+            0o001 => Fifo,
+            0o002 => CharDevice,
+            0o004 => Dir,
+            0o006 => BlockDevice,
+            0o010 => File,
+            0o012 => Symlink,
+            0o014 => Socket,
+            0o016 => Whiteout,
+            _ => Unknown,
+        }
+    }
+}
+
+/// Enum for specifying the context / "who" accesses in [is_allowed]
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub enum Accessor {
+    Other,
+    Group,
+    User,
+}
+
+/// Enum for specifying the type of access in [is_allowed]
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub enum Access {
+    /// (Beware: execute has various meanings depending on the type of file)
+    Execute,
+    Write,
+    Read,
+}
+
+/// Check whether `mode` represents an allowed (`true`) or denied (`false`) access
+pub fn is_allowed(by: Accessor, ty: Access, mode: u32) -> bool {
+    use Access::*;
+    use Accessor::*;
+    let by = match by {
+        User => 2,
+        Group => 1,
+        Other => 0,
+    };
+    let bits = (mode >> (3 * by)) & 0o7;
+    let ty = match ty {
+        Read => 2,
+        Write => 1,
+        Execute => 0,
+    };
+    bits & (1 << ty) != 0
+}
+
 /// Returns true if this mode represents a regular file.
 ///
 /// ```
 /// assert_eq!(unix_mode::is_file(0o0041777), false);
 /// assert_eq!(unix_mode::is_file(0o0100640), true);
 /// ```
 pub fn is_file(mode: u32) -> bool {
-    type_bits(mode) == 0o010
+    Type::from(mode) == Type::File
 }
 
 /// Returns true if this mode represents a directory.
@@ -60,7 +138,7 @@ pub fn is_file(mode: u32) -> bool {
 /// assert_eq!(unix_mode::is_dir(0o0100640), false);
 /// ```
 pub fn is_dir(mode: u32) -> bool {
-    type_bits(mode) == 0o004
+    Type::from(mode) == Type::Dir
 }
 
 /// Returns true if this mode represents a symlink.
@@ -70,27 +148,27 @@ pub fn is_dir(mode: u32) -> bool {
 /// assert_eq!(unix_mode::is_symlink(0o0120755), true);
 /// ```
 pub fn is_symlink(mode: u32) -> bool {
-    type_bits(mode) == 0o012
+    Type::from(mode) == Type::Symlink
 }
 
 /// Returns true if this mode represents a fifo, also known as a named pipe.
 pub fn is_fifo(mode: u32) -> bool {
-    type_bits(mode) == 0o001
+    Type::from(mode) == Type::Fifo
 }
 
 /// Returns true if this mode represents a character device.
 pub fn is_char_device(mode: u32) -> bool {
-    type_bits(mode) == 0o002
+    Type::from(mode) == Type::CharDevice
 }
 
 /// Returns true if this mode represents a block device.
 pub fn is_block_device(mode: u32) -> bool {
-    type_bits(mode) == 0o006
+    Type::from(mode) == Type::BlockDevice
 }
 
 /// Returns true if this mode represents a Unix-domain socket.
 pub fn is_socket(mode: u32) -> bool {
-    type_bits(mode) == 0o014
+    Type::from(mode) == Type::Socket
 }
 
 /// Returns true if the set-user-ID bit is set
@@ -130,71 +208,43 @@ pub fn is_sticky(mode: u32) -> bool {
 pub fn to_string(mode: u32) -> String {
     // This is decoded "by hand" here so that it'll work
     // on non-Unix platforms.
+    use Access::*;
+    use Accessor::*;
+    use Type::*;
 
-    fn bitset(a: u32, b: u32) -> bool {
-        a & b != 0
-    }
-
-    fn permch(mode: u32, b: u32, ch: char) -> char {
-        if bitset(mode, b) {
-            ch
-        } else {
-            '-'
-        }
-    }
-
-    let mut s = String::with_capacity(10);
-    s.push(match (mode >> 12) & 0o17 {
-        0o001 => 'p', // pipe/fifo
-        0o002 => 'c', // character dev
-        0o004 => 'd', // directory
-        0o006 => 'b', // block dev
-        0o010 => '-', // regular file
-        0o012 => 'l', // link
-        0o014 => 's', // socket
-        0o016 => 'w', // whiteout
-        _ => '?',     // unknown
-    });
     let setuid = is_setuid(mode);
     let setgid = is_setgid(mode);
     let sticky = is_sticky(mode);
-    s.push(permch(mode, 0o400, 'r'));
-    s.push(permch(mode, 0o200, 'w'));
-    let usrx = bitset(mode, 0o100);
-    if setuid && usrx {
-        s.push('s')
-    } else if setuid && !usrx {
-        s.push('S')
-    } else if usrx {
-        s.push('x')
-    } else {
-        s.push('-')
-    }
-    // group
-    s.push(permch(mode, 0o40, 'r'));
-    s.push(permch(mode, 0o20, 'w'));
-    let grpx = bitset(mode, 0o10);
-    if setgid && grpx {
-        s.push('s')
-    } else if setgid && !grpx {
-        s.push('S')
-    } else if grpx {
-        s.push('x')
-    } else {
-        s.push('-')
-    }
-    // other
-    s.push(permch(mode, 0o4, 'r'));
-    s.push(permch(mode, 0o2, 'w'));
-    let otherx = bitset(mode, 0o1);
-    if sticky && otherx {
-        s.push('t')
-    } else if sticky && !otherx {
-        s.push('T')
-    } else if otherx {
-        s.push('x')
-    } else {
-        s.push('-')
+
+    let mut s = String::with_capacity(10);
+    s.push(match Type::from(mode) {
+        Fifo => 'p',
+        CharDevice => 'c',
+        Dir => 'd',
+        BlockDevice => 'b',
+        File => '-',
+        Symlink => 'l',
+        Socket => 's',
+        Whiteout => 'w',
+        Unknown => '?',
+    });
+    for accessor in [User, Group, Other] {
+        for access in [Read, Write, Execute] {
+            s.push(
+                match (access, accessor, is_allowed(accessor, access, mode)) {
+                    (Execute, User, true) if setuid => 's',
+                    (Execute, User, false) if setuid => 'S',
+                    (Execute, Group, true) if setgid => 's',
+                    (Execute, Group, false) if setgid => 'S',
+                    (Execute, Other, true) if sticky => 't',
+                    (Execute, Other, false) if sticky => 'T',
+                    (Execute, _, true) => 'x',
+                    (Write, _, true) => 'w',
+                    (Read, _, true) => 'r',
+                    (_, _, false) => '-',
+                },
+            );
+        }
     }
     s
 }
@@ -229,6 +279,20 @@ mod unix_tests {
         // we can't make one (without root.)
     }
 
+    /// Test [is_allowed] against files likely to already exist on a Unix system.
+    #[test]
+    fn existing_file_perms() {
+        use Access::*;
+        use Accessor::*;
+        for by in [User, Group, Other] {
+            assert!(is_allowed(by, Read, file_mode("/")));
+            assert!(is_allowed(by, Execute, file_mode("/")));
+            assert!(is_allowed(by, Write, file_mode("/dev/null")));
+        }
+        assert!(!is_allowed(Other, Write, file_mode("/dev/")));
+        assert!(!is_allowed(Other, Execute, file_mode("/dev/null")));
+    }
+
     #[test]
     fn stat_created_symlink() {
         let tmp_dir = tempdir().unwrap();