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
impl PosixACL
sourcepub fn new(file_mode: u32) -> PosixACL
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"
);
sourcepub fn with_capacity(capacity: usize) -> PosixACL
pub fn with_capacity(capacity: usize) -> PosixACL
Create an empty ACL with capacity. NB! Empty ACLs are NOT considered valid.
sourcepub fn read_acl<P: AsRef<Path>>(path: P) -> Result<PosixACL, ACLError>
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).
sourcepub fn read_default_acl<P: AsRef<Path>>(path: P) -> Result<PosixACL, ACLError>
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.
sourcepub fn write_acl<P: AsRef<Path>>(&mut self, path: P) -> Result<(), ACLError>
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. SeePosixACL::validate()
for more information.
sourcepub fn write_default_acl<P: AsRef<Path>>(
&mut self,
path: P
) -> Result<(), ACLError>
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. SeePosixACL::validate()
for more information.
sourcepub fn entries(&self) -> Vec<ACLEntry>
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.
sourcepub fn set(&mut self, qual: Qualifier, perm: u32)
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.
sourcepub fn remove(&self, qual: Qualifier) -> Option<u32>
pub fn remove(&self, qual: Qualifier) -> Option<u32>
Remove entry with matching qual
. If found, returns the matching perm
, otherwise None
sourcepub fn fix_mask(&mut self)
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.
sourcepub fn as_text(&self) -> String
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.
sourcepub fn validate(&self) -> Result<(), ACLError>
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()
.
Errors
ACLError::ValidationError
: The ACL failed validation.
Unfortunately it is not possible to provide detailed error reasons, but mainly it can be:
- Required entries are missing (
UserObj
,GroupObj
,Mask
andOther
). - ACL contains entries that are not unique.
sourcepub fn into_raw(self) -> acl_t
pub fn into_raw(self) -> acl_t
Consumes the PosixACL
, returning the wrapped acl_t
.
This can then be used directly in FFI calls to the acl library.
To avoid a memory leak, the acl_t
must either:
- Be converted back to a
PosixACL
usingPosixACL::from_raw()
- Have
acl_free()
called on it
sourcepub unsafe fn from_raw(acl: acl_t) -> Self
pub unsafe fn from_raw(acl: acl_t) -> Self
Constructs a PosixACL
from a raw acl_t
. You should treat the acl_t
as being ‘consumed’ by this function.
Safety
The acl_t
must be a valid ACL (not (acl_t)NULL
) acl returned
either PosixACL::into_raw()
or another ACL library function.
Improper usage of this function may lead to memory unsafety (e.g. calling it twice on the same acl may lead to a double free).
Trait Implementations§
source§impl Debug for PosixACL
impl Debug for PosixACL
Custom debug formatting, since output PosixACL { acl: 0x7fd74c000ca8 }
is not very helpful.