Struct PosixACL

Source

pub struct PosixACL { /* private fields */ }

Expand description

The ACL of a file.

Implements a “mapping-like” interface where key is the Qualifier enum and value is u32 containing permission bits. Using methods get(qual) -> perms, set(qual, perms), remove(qual).

Implementations§

Source §

impl PosixACL

Source

pub fn new(file_mode: u32) -> PosixACL

Convert a file mode (“chmod” number) into a “minimal” ACL. This is the primary constructor. Note that modes are usually expressed in octal, e.g. PosixACL::new(0o644)

This creates the minimal required entries. By the POSIX ACL spec, every valid ACL must contain at least three entries: UserObj, GroupObj and Other, corresponding to file mode bits.

Input bits higher than 9 (e.g. SUID flag, etc) are ignored.

use posix_acl::PosixACL;
assert_eq!(
    PosixACL::new(0o751).as_text(),
    "user::rwx\ngroup::r-x\nother::--x\n"
);

Source

pub fn empty() -> PosixACL

Create an empty ACL. NB! Empty ACLs are NOT considered valid.

Source

pub fn with_capacity(capacity: usize) -> PosixACL

Create an empty ACL with capacity. NB! Empty ACLs are NOT considered valid.

Source

pub fn read_acl<P: AsRef<Path>>(path: P) -> Result<PosixACL, ACLError>

Read a path’s access ACL and return as PosixACL object.

use posix_acl::PosixACL;
let acl = PosixACL::read_acl("/etc/shells").unwrap();

§Errors

ACLError::IoError: Filesystem errors (file not found, permission denied, etc).

It is NOT an error if the provided path has no ACL; a minimal ACL will be returned.

Source

pub fn read_default_acl<P: AsRef<Path>>(path: P) -> Result<PosixACL, ACLError>

Read a directory’s default ACL and return as PosixACL object. This will fail if path is not a directory.

Default ACL determines permissions for new files and subdirectories created in the directory.

use posix_acl::PosixACL;
let acl = PosixACL::read_default_acl("/tmp").unwrap();

§Errors

ACLError::IoError: Filesystem errors (file not found, permission denied, etc).
Passing a non-directory path will fail with ‘permission denied’ error on Linux.

It is NOT an error if the provided path has no ACL; an empty ACL will be returned.

Source

pub fn write_acl<P: AsRef<Path>>(&mut self, path: P) -> Result<(), ACLError>

Validate and write this ACL to a path’s access ACL. Overwrites any existing access ACL.

Note: this function takes mutable self because it automatically re-calculates the magic Mask entry.

§Errors

ACLError::IoError: Filesystem errors (file not found, permission denied, etc).
ACLError::ValidationError: The ACL failed validation. See PosixACL::validate() for more information.

Source

pub fn write_default_acl<P: AsRef<Path>>( &mut self, path: P, ) -> Result<(), ACLError>

Validate and write this ACL to a directory’s default ACL. Overwrites existing default ACL. This will fail if path is not a directory.

Default ACL determines permissions for new files and subdirectories created in the directory.

Note: this function takes mutable self because it automatically re-calculates the magic Mask entry.

§Errors

ACLError::IoError: Filesystem errors (file not found, permission denied, etc).
ACLError::ValidationError: The ACL failed validation. See PosixACL::validate() for more information.

Source

pub fn entries(&self) -> Vec<ACLEntry>

Get all ACLEntry items. The POSIX ACL C API does not allow multiple parallel iterators so we return a materialized vector just to be safe.

Source

pub fn get(&self, qual: Qualifier) -> Option<u32>

Get the current perm value of qual, if any.

Source

pub fn set(&mut self, qual: Qualifier, perm: u32)

Set the permission of qual to perm. If this qual already exists, it is updated, otherwise a new one is added.

perm must be a combination of the ACL_ constants, combined by binary OR.

Source

pub fn remove(&self, qual: Qualifier) -> Option<u32>

Remove entry with matching qual. If found, returns the matching perm, otherwise None

Source

pub fn fix_mask(&mut self)

Re-calculate the Qualifier::Mask entry.

Usually there is no need to call this directly, as this is done during write_acl/write_default_acl() automatically.

Source

pub fn as_text(&self) -> String

Return the textual representation of the ACL. Individual entries are separated by newline ('\n').

UID/GID are automatically resolved to names by the platform.

§Panics

When platform returns a string that is not valid UTF-8.

Source

pub fn validate(&self) -> Result<(), ACLError>

Call the platform’s validation function.

Usually there is no need to explicitly call this method, the write_acl() method validates ACL prior to writing. If you didn’t take special care of the Mask entry, it may be necessary to call fix_mask() prior to validate().