Exacl

https://docs.rs/exacl/latest/exacl/
Admin
The exacl crate provides functionalities to manipulate file system access control lists (ACL) on...
Tokens:13,720
Snippets:147
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### setfacl Linux Example

Source: https://docs.rs/exacl/latest/exacl/fn.setfacl.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example of setting ACLs on Linux, where entries must include permission modes and mask entries are required if named users or groups are present.

```rust
use exacl::{setfacl, AclEntry, Flag, Perm};

let entries = vec![
    AclEntry::allow_user("", Perm::READ | Perm::WRITE, None),
    AclEntry::allow_group("", Perm::READ, None),
    AclEntry::allow_other(Perm::empty(), None),
    AclEntry::allow_user("some_user", Perm::READ | Perm::WRITE, None),
];

setfacl(&["./tmp/foo"], &entries, None)?;
```

--------------------------------

### setfacl macOS Example

Source: https://docs.rs/exacl/latest/exacl/fn.setfacl.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example of setting ACLs on macOS, where entries can explicitly allow or deny access to users and groups.

```rust
use exacl::{setfacl, AclEntry, Flag, Perm};

let entries = vec![
    AclEntry::allow_user("some_user", Perm::READ | Perm::WRITE, None),
    AclEntry::deny_group("some_group", Perm::WRITE, None)
];

setfacl(&["./tmp/foo"], &entries, None)?;
```

--------------------------------

### Sample ACL input format

Source: https://docs.rs/exacl/latest/exacl/fn.from_reader.html

Example of valid ACL text input that can be parsed by from_reader.

```text
allow::group:admin:read,write
g:admin:rw  # ignored
d:u:chip:rw
deny:file_inherit:user:chet:rwx
```

--------------------------------

### Sample ACL output

Source: https://docs.rs/exacl/latest/exacl/fn.to_writer.html

An example of the text output generated by the to_writer function.

```text
allow::group:admin:read,write
```

--------------------------------

### fn from_reader<R: Read>(reader: R) -> Result<Vec<AclEntry>>

Source: https://docs.rs/exacl/latest/exacl/fn.from_reader.html?search=std%3A%3Avec

Reads ACL entries from a text source. Each entry is expected on a separate line, with support for comments starting with '#'.

```APIDOC
## fn from_reader<R: Read>(reader: R) -> Result<Vec<AclEntry>>

### Description
Reads ACL entries from a text-based reader. Each entry is presented on a separate line, and comments starting with '#' are ignored.

### Parameters
- **reader** (R: Read) - The input source containing the ACL text data.

### Returns
- **Result<Vec<AclEntry>>** - A vector of parsed ACL entries or an `io::Error` if parsing fails.

### Supported Formats
- `<allow>:<flags>:<kind>:<name>:<perms>`
- `<flags>:<kind>:<name>:<perms>`
- `<kind>:<name>:<perms>`

### Example Input
```
allow::group:admin:read,write
d:u:chip:rw
deny:file_inherit:user:chet:rwx
```
```

--------------------------------

### pub fn from_reader<R: Read>(reader: R) -> Result<Vec<AclEntry>>

Source: https://docs.rs/exacl/latest/exacl/fn.from_reader.html

Reads ACL entries from a provided reader. Each entry is expected on a separate line, with support for comments starting with '#'.

```APIDOC
## from_reader

### Description
Reads ACL entries from text provided by a reader. Each ACL entry is presented on a separate line, and comments starting with '#' are ignored.

### Signature
`pub fn from_reader<R: Read>(reader: R) -> Result<Vec<AclEntry>>`

### Supported Formats
- `<allow>:<flags>:<kind>:<name>:<perms>`
- `<flags>:<kind>:<name>:<perms>`
- `<kind>:<name>:<perms>`

### Parameters
- **reader** (R: Read) - The source to read ACL entries from.

### Errors
Returns an `io::Error` on failure.
```

--------------------------------

### from_reader

Source: https://docs.rs/exacl/latest/exacl/fn.from_reader.html?search=u32+-%3E+bool

Reads ACL entries from a text source where each entry is on a separate line. Comments starting with '#' are ignored, and whitespace within fields is trimmed.

```APIDOC
## fn from_reader<R: Read>(reader: R) -> Result<Vec<AclEntry>>

### Description
Reads ACL entries from a text source. Each entry is presented on a separate line, and comments starting with '#' are ignored.

### Parameters
- **reader** (R: Read) - The source to read ACL entries from.

### Returns
- **Result<Vec<AclEntry>>** - A vector of parsed ACL entries or an io::Error on failure.

### Supported Formats
- <allow>:<flags>:<kind>:<name>:<perms>
- <flags>:<kind>:<name>:<perms>
- <kind>:<name>:<perms>

### Example
```rust
use exacl::from_reader;
use std::io::Cursor;

let data = "allow::group:admin:read,write\nd:u:chip:rw";
let entries = from_reader(Cursor::new(data));
```
```

--------------------------------

### Constructing AclEntry Instances

Source: https://docs.rs/exacl/latest/exacl/struct.AclEntry.html

Methods for creating allow or deny entries for users, groups, masks, and others. Note that some methods are platform-specific to FreeBSD, Linux, or macOS.

```rust
pub fn allow_user<F>(name: &str, perms: Perm, flags: F) -> AclEntry
where F: Into<Option<Flag>>,
```

```rust
pub fn allow_group<F>(name: &str, perms: Perm, flags: F) -> AclEntry
where F: Into<Option<Flag>>,
```

```rust
pub fn allow_mask<F>(perms: Perm, flags: F) -> AclEntry
where F: Into<Option<Flag>>,
```

```rust
pub fn allow_other<F>(perms: Perm, flags: F) -> AclEntry
where F: Into<Option<Flag>>,
```

```rust
pub fn deny_user<F>(name: &str, perms: Perm, flags: F) -> AclEntry
where F: Into<Option<Flag>>,
```

```rust
pub fn deny_group<F>(name: &str, perms: Perm, flags: F) -> AclEntry
where F: Into<Option<Flag>>,
```

--------------------------------

### AclEntry Construction Methods

Source: https://docs.rs/exacl/latest/exacl/struct.AclEntry.html

Methods for creating new AclEntry instances for different principals and permission types.

```APIDOC
## pub fn allow_user<F>(name: &str, perms: Perm, flags: F) -> AclEntry
Construct an ALLOW access control entry for a user.

## pub fn allow_group<F>(name: &str, perms: Perm, flags: F) -> AclEntry
Construct an ALLOW access control entry for a group.

## pub fn allow_mask<F>(perms: Perm, flags: F) -> AclEntry
Construct an ALLOW access control entry for mask. (Available on FreeBSD or Linux only)

## pub fn allow_other<F>(perms: Perm, flags: F) -> AclEntry
Construct an ALLOW access control entry for other. (Available on FreeBSD or Linux only)

## pub fn deny_user<F>(name: &str, perms: Perm, flags: F) -> AclEntry
Construct a DENY access control entry for a user. (Available on FreeBSD or macOS only)

## pub fn deny_group<F>(name: &str, perms: Perm, flags: F) -> AclEntry
Construct a DENY access control entry for a group. (Available on FreeBSD or macOS only)
```

--------------------------------

### AclEntry Construction Methods

Source: https://docs.rs/exacl/latest/exacl/struct.AclEntry.html?search=std%3A%3Avec

Methods for creating specific types of access control entries.

```APIDOC
## AclEntry::allow_user(name: &str, perms: Perm, flags: F) -> AclEntry
Constructs an ALLOW access control entry for a user.

## AclEntry::allow_group(name: &str, perms: Perm, flags: F) -> AclEntry
Constructs an ALLOW access control entry for a group.

## AclEntry::allow_mask(perms: Perm, flags: F) -> AclEntry
Constructs an ALLOW access control entry for mask (FreeBSD/Linux only).

## AclEntry::allow_other(perms: Perm, flags: F) -> AclEntry
Constructs an ALLOW access control entry for other (FreeBSD/Linux only).

## AclEntry::deny_user(name: &str, perms: Perm, flags: F) -> AclEntry
Constructs a DENY access control entry for a user (FreeBSD/macOS only).

## AclEntry::deny_group(name: &str, perms: Perm, flags: F) -> AclEntry
Constructs a DENY access control entry for a group (FreeBSD/macOS only).
```

--------------------------------

### from_mode(mode: u32) -> Vec<AclEntry>

Source: https://docs.rs/exacl/latest/exacl/fn.from_mode.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Constructs a minimal ACL from the traditional mode permission bits. This function is available on FreeBSD or Linux only.

```APIDOC
## from_mode

### Description
Constructs a minimal ACL from the traditional `mode` permission bits. Returns a `Vec<AclEntry>` for a minimal ACL with three entries corresponding to the owner/group/other permission bits given in `mode`. Extra bits outside the mask 0o777 are ignored.

### Signature
`pub fn from_mode(mode: u32) -> Vec<AclEntry>`

### Parameters
- **mode** (u32) - The traditional permission bits to convert.

### Returns
- **Vec<AclEntry>** - A vector containing the minimal ACL entries.
```

--------------------------------

### from_mode(mode: u32) -> Vec<AclEntry>

Source: https://docs.rs/exacl/latest/exacl/fn.from_mode.html

Constructs a minimal ACL from the traditional mode permission bits. This function is available on FreeBSD or Linux only.

```APIDOC
## from_mode

### Description
Constructs a minimal ACL from the traditional `mode` permission bits. Returns a `Vec<AclEntry>` for a minimal ACL with three entries corresponding to the owner/group/other permission bits given in `mode`. Extra bits outside the mask 0o777 are ignored.

### Signature
`pub fn from_mode(mode: u32) -> Vec<AclEntry>`

### Parameters
- **mode** (u32) - The traditional permission bits used to construct the ACL.

### Returns
- **Vec<AclEntry>** - A vector containing the minimal ACL entries.
```

--------------------------------

### fn from_mode(mode: u32) -> Vec<AclEntry>

Source: https://docs.rs/exacl/latest/exacl/fn.from_mode.html?search=u32+-%3E+bool

Constructs a minimal ACL from the traditional mode permission bits. This function is available on FreeBSD or Linux only.

```APIDOC
## fn from_mode(mode: u32) -> Vec<AclEntry>

### Description
Construct a minimal ACL from the traditional `mode` permission bits. Returns a `Vec<AclEntry>` for a minimal ACL with three entries corresponding to the owner/group/other permission bits given in `mode`. Extra bits outside the mask 0o777 are ignored.

### Signature
`pub fn from_mode(mode: u32) -> Vec<AclEntry>`

### Parameters
- **mode** (u32) - The traditional permission bits to convert. Bits outside the 0o777 mask are ignored.

### Returns
- **Vec<AclEntry>** - A vector containing the minimal ACL entries.
```

--------------------------------

### pub fn to_writer<W: Write>(writer: W, entries: &[AclEntry]) -> Result<()>

Source: https://docs.rs/exacl/latest/exacl/fn.to_writer.html

Writes ACL entries to a writer in a colon-separated text format. Each entry is printed on a new line with fields for allow/deny, flags, kind, name, and permissions.

```APIDOC
## Function: to_writer

### Description
Writes a slice of ACL entries to the provided writer in a text-based format. Each entry is terminated by a newline.

### Signature
`pub fn to_writer<W: Write>(writer: W, entries: &[AclEntry]) -> Result<()>`

### Format
Each line follows the format: `<allow>:<flags>:<kind>:<name>:<perms>`
- **allow**: "allow" or "deny"
- **flags**: comma-separated list of flags
- **kind**: "user", "group", "other", "mask", or "unknown"
- **name**: user/group name or decimal ID
- **perms**: comma-separated list of permissions

### Errors
Returns an `io::Error` if the write operation fails.
```

--------------------------------

### from_mode(mode: u32) -> Vec<AclEntry>

Source: https://docs.rs/exacl/latest/exacl/fn.from_mode.html?search=

Constructs a minimal ACL from the traditional mode permission bits. This function returns a Vec<AclEntry> containing three entries corresponding to the owner, group, and other permission bits provided in the mode argument. Bits outside the 0o777 mask are ignored.

```APIDOC
## from_mode

### Signature
`pub fn from_mode(mode: u32) -> Vec<AclEntry>`

### Description
Constructs a minimal ACL from the traditional `mode` permission bits. Returns a `Vec<AclEntry>` for a minimal ACL with three entries corresponding to the owner/group/other permission bits given in `mode`.

### Parameters
- **mode** (u32) - The traditional permission bits (e.g., 0o644). Extra bits outside the mask 0o777 are ignored.

### Returns
- **Vec<AclEntry>** - A vector containing the minimal ACL entries.

### Platform Availability
Available on **FreeBSD or Linux** only.
```

--------------------------------

### AclEntry Constructors

Source: https://docs.rs/exacl/latest/exacl/struct.AclEntry.html?search=

Methods for constructing various types of access control entries.

```APIDOC
## AclEntry Constructors

### allow_user(name: &str, perms: Perm, flags: F) -> AclEntry
Constructs an ALLOW access control entry for a user.

### allow_group(name: &str, perms: Perm, flags: F) -> AclEntry
Constructs an ALLOW access control entry for a group.

### allow_mask(perms: Perm, flags: F) -> AclEntry
Constructs an ALLOW access control entry for mask (FreeBSD or Linux only).

### allow_other(perms: Perm, flags: F) -> AclEntry
Constructs an ALLOW access control entry for other (FreeBSD or Linux only).

### deny_user(name: &str, perms: Perm, flags: F) -> AclEntry
Constructs a DENY access control entry for a user (FreeBSD or macOS only).

### deny_group(name: &str, perms: Perm, flags: F) -> AclEntry
Constructs a DENY access control entry for a group (FreeBSD or macOS only).
```

--------------------------------

### pub fn to_string(entries: &[AclEntry]) -> Result<String>

Source: https://docs.rs/exacl/latest/exacl/fn.to_string.html?search=

Serializes a collection of ACL entries into a text format.

```APIDOC
## Function: to_string

### Description
Writes a slice of `AclEntry` objects to a string. This function follows the same formatting rules as `to_writer`.

### Signature
`pub fn to_string(entries: &[AclEntry]) -> Result<String>`

### Parameters
- **entries** (&[AclEntry]) - Required - A slice of ACL entries to be converted to string format.

### Returns
- **Result<String>** - Returns a `String` containing the formatted ACL entries on success, or an `io::Error` on failure.
```

--------------------------------

### Manipulate file system ACLs

Source: https://docs.rs/exacl/latest/exacl/index.html?search=std%3A%3Avec

Demonstrates retrieving an ACL from a file, printing its entries, modifying the list, and applying the updated ACL back to the file.

```rust
use exacl::{getfacl, setfacl, AclEntry, Perm};

// Get the ACL from "./tmp/foo".
let mut acl = getfacl("./tmp/foo", None)?;

// Print the contents of the ACL.
for entry in &acl {
    println!("{entry}");
}

// Add an ACL entry to the end.
acl.push(AclEntry::allow_user("some_user", Perm::READ, None));

// Set the ACL for "./tmp/foo".
setfacl(&["./tmp/foo"], &acl, None)?;
```

--------------------------------

### pub fn to_writer<W: Write>(writer: W, entries: &[AclEntry]) -> Result<()>

Source: https://docs.rs/exacl/latest/exacl/fn.to_writer.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Writes ACL entries to the provided writer in a text format. Each entry is printed on a separate line with fields separated by colons.

```APIDOC
## Function: to_writer

### Description
Writes a slice of `AclEntry` objects to a writer in a specific text format. Each entry is terminated by a newline.

### Signature
`pub fn to_writer<W: Write>(writer: W, entries: &[AclEntry]) -> Result<()>`

### Parameters
- **writer** (W: Write) - The destination to write the ACL entries to.
- **entries** (&[AclEntry]) - A slice of ACL entries to be serialized.

### Format
Each entry follows the format: `<allow>:<flags>:<kind>:<name>:<perms>`
- **allow**: "allow" or "deny"
- **flags**: comma-separated list of flags
- **kind**: "user", "group", "other", "mask", or "unknown"
- **name**: user/group name or decimal ID
- **perms**: comma-separated list of permissions

### Errors
Returns an `io::Error` if the write operation fails.
```

--------------------------------

### Basic Usage of getfacl

Source: https://docs.rs/exacl/latest/exacl/fn.getfacl.html

Retrieves the ACL entries for a specified file path.

```rust
use exacl::getfacl;

let entries = getfacl("./tmp/foo", None)?;
```

--------------------------------

### AclEntry::allow_user

Source: https://docs.rs/exacl/latest/exacl/struct.AclEntry.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Constructs an ALLOW access control entry for a specific user.

```APIDOC
## pub fn allow_user<F>(name: &str, perms: Perm, flags: F) -> AclEntry

### Description
Constructs an ALLOW access control entry for a user.

### Parameters
- **name** (&str) - The name of the user or decimal uid.
- **perms** (Perm) - The permission bits for the entry.
- **flags** (F) - Flags indicating inheritance or other properties (must implement Into<Option<Flag>>).
```

--------------------------------

### AclEntry::deny_user

Source: https://docs.rs/exacl/latest/exacl/struct.AclEntry.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Constructs a DENY access control entry for a specific user (FreeBSD or macOS only).

```APIDOC
## pub fn deny_user<F>(name: &str, perms: Perm, flags: F) -> AclEntry

### Description
Constructs a DENY access control entry for a user. Available on FreeBSD or macOS only.

### Parameters
- **name** (&str) - The name of the user or decimal uid.
- **perms** (Perm) - The permission bits for the entry.
- **flags** (F) - Flags indicating inheritance or other properties (must implement Into<Option<Flag>>).
```

--------------------------------

### pub fn to_string(entries: &[AclEntry]) -> Result<String>

Source: https://docs.rs/exacl/latest/exacl/fn.to_string.html

Converts a slice of ACL entries into a text string. This function returns an io::Error if the operation fails.

```APIDOC
## Function: to_string

### Description
Writes a slice of ACL entries to a string format. This is a utility function for serializing ACL data.

### Signature
`pub fn to_string(entries: &[AclEntry]) -> Result<String>`

### Parameters
- **entries** (&[AclEntry]) - Required - A slice of ACL entries to be converted to text.

### Returns
- **Result<String>** - Returns a string containing the formatted ACL entries on success, or an `io::Error` on failure.
```

--------------------------------

### getfacl

Source: https://docs.rs/exacl/latest/exacl/fn.getfacl.html?search=u32+-%3E+bool

Retrieves the access control list for a given path.

```APIDOC
## fn getfacl<P, O>(path: P, options: O) -> Result<Vec<AclEntry>>

### Description
Retrieves the access control list (ACL) for a file or directory. On success, it returns a vector of `AclEntry` objects. The specific behavior and supported options depend on the underlying platform (macOS or Linux).

### Parameters
- **path** (P: AsRef<Path>) - The path to the file or directory.
- **options** (O: Into<Option<AclOption>>) - Optional configuration for the ACL retrieval.

### Returns
- **Result<Vec<AclEntry>>** - A vector of ACL entries on success, or an `io::Error` on failure.

### Example
```rust
use exacl::getfacl;

let entries = getfacl("./tmp/foo", None)?;
```
```

--------------------------------

### Function signature for from_str

Source: https://docs.rs/exacl/latest/exacl/fn.from_str.html

The function signature for parsing ACL entries from a string.

```rust
pub fn from_str(s: &str) -> Result<Vec<AclEntry>>
```

--------------------------------

### pub fn to_string(entries: &[AclEntry]) -> Result<String>

Source: https://docs.rs/exacl/latest/exacl/fn.to_string.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Serializes a slice of ACL entries into a string. This function follows the same format as to_writer.

```APIDOC
## Function: to_string

### Description
Writes a collection of ACL entries to a string format.

### Signature
`pub fn to_string(entries: &[AclEntry]) -> Result<String>`

### Parameters
- **entries** (&[AclEntry]) - A slice of AclEntry objects to be serialized.

### Returns
- **Result<String>** - Returns the serialized string on success, or an `io::Error` on failure.
```

--------------------------------

### Define Perm struct

Source: https://docs.rs/exacl/latest/exacl/struct.Perm.html

The definition of the Perm struct.

```rust
pub struct Perm(/* private fields */);
```

--------------------------------

### getfacl(path, options)

Source: https://docs.rs/exacl/latest/exacl/fn.getfacl.html?search=

Retrieves the access control list (ACL) for a given file or directory path.

```APIDOC
## fn getfacl

### Description
Get access control list (ACL) for a file or directory. On success, returns a vector of `AclEntry` with all access control entries for the specified path.

### Signature
`pub fn getfacl<P, O>(path: P, options: O) -> Result<Vec<AclEntry>>`

### Parameters
- **path** (AsRef<Path>) - Required - The path to the file or directory.
- **options** (Into<Option<AclOption>>) - Required - Optional configuration for retrieving the ACL (e.g., SYMLINK_ACL, DEFAULT_ACL).

### Platform Notes
- **macOS**: Returns extended entries. Symlinks are followed by default; use `AclOption::SYMLINK_ACL` to target the symlink itself.
- **Linux**: Returns access and default ACLs. Symlinks are followed by default; `AclOption::DEFAULT_ACL` restricts results to default ACL entries.

### Errors
Returns an `io::Error` on failure.

### Example
```rust
use exacl::getfacl;

let entries = getfacl("./tmp/foo", None)?;
```
```

--------------------------------

### getfacl(path, options)

Source: https://docs.rs/exacl/latest/exacl/fn.getfacl.html

Retrieves the access control list (ACL) for a given file or directory path.

```APIDOC
## getfacl(path, options)

### Description
Retrieves the access control list (ACL) for a file or directory. On success, it returns a vector of AclEntry objects representing the access control entries for the specified path.

### Signature
`pub fn getfacl<P, O>(path: P, options: O) -> Result<Vec<AclEntry>>`

### Parameters
- **path** (P: AsRef<Path>) - Required - The file system path to retrieve the ACL for.
- **options** (O: Into<Option<AclOption>>) - Optional - Configuration options such as AclOption::SYMLINK_ACL or AclOption::DEFAULT_ACL.

### Errors
Returns an `io::Error` if the operation fails.

### Example
```rust
use exacl::getfacl;

let entries = getfacl("./tmp/foo", None)?;
```
```

--------------------------------

### Serialize ACL entries to string

Source: https://docs.rs/exacl/latest/exacl/fn.to_string.html?search=

Converts a slice of AclEntry objects into a string. Refer to to_writer for details on the output format.

```rust
pub fn to_string(entries: &[AclEntry]) -> Result<String>
```

--------------------------------

### pub fn from_str(s: &str) -> Result<Vec<AclEntry>>

Source: https://docs.rs/exacl/latest/exacl/fn.from_str.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Parses a string into a vector of ACL entries. Returns an io::Error if the parsing fails.

```APIDOC
## Function: from_str

### Description
Reads ACL entries from a provided string. The format expected is the same as that used by `from_reader`.

### Signature
`pub fn from_str(s: &str) -> Result<Vec<AclEntry>>`

### Parameters
- **s** (&str) - The input string containing ACL entries.

### Errors
Returns an `io::Error` if the input string cannot be parsed into valid ACL entries.
```

--------------------------------

### pub fn from_str(s: &str) -> Result<Vec<AclEntry>>

Source: https://docs.rs/exacl/latest/exacl/fn.from_str.html?search=

Parses ACL entries from a provided string input. Returns a Result containing a vector of AclEntry objects or an io::Error on failure.

```APIDOC
## pub fn from_str(s: &str) -> Result<Vec<AclEntry>>

### Description
Reads and parses ACL entries from a text string. The format expected is the same as that used by `from_reader`.

### Parameters
- **s** (&str) - Required - The string containing the ACL entries to be parsed.

### Returns
- **Result<Vec<AclEntry>>** - Returns a vector of `AclEntry` objects on success, or an `io::Error` if parsing fails.
```

--------------------------------

### pub fn from_str(s: &str) -> Result<Vec<AclEntry>>

Source: https://docs.rs/exacl/latest/exacl/fn.from_str.html

Parses a string containing ACL entries into a list of AclEntry structures. Returns an io::Error if the parsing fails.

```APIDOC
## from_str

### Description
Reads and parses ACL entries from a provided string slice. This function is used to convert text-based ACL definitions into structured data.

### Signature
`pub fn from_str(s: &str) -> Result<Vec<AclEntry>>`

### Parameters
- **s** (&str) - Required - The string containing the ACL entries to be parsed.

### Returns
- **Result<Vec<AclEntry>>** - A vector of parsed ACL entries on success, or an `io::Error` if the input string is malformed or invalid.
```

--------------------------------

### AclEntry::allow_group

Source: https://docs.rs/exacl/latest/exacl/struct.AclEntry.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Constructs an ALLOW access control entry for a specific group.

```APIDOC
## pub fn allow_group<F>(name: &str, perms: Perm, flags: F) -> AclEntry

### Description
Constructs an ALLOW access control entry for a group.

### Parameters
- **name** (&str) - The name of the group or decimal gid.
- **perms** (Perm) - The permission bits for the entry.
- **flags** (F) - Flags indicating inheritance or other properties (must implement Into<Option<Flag>>).
```

--------------------------------

### from_str

Source: https://docs.rs/exacl/latest/exacl/fn.from_str.html?search=std%3A%3Avec

Parses ACL entries from a string input. Returns a Result containing a vector of AclEntry objects or an io::Error on failure.

```APIDOC
## fn from_str

### Description
Reads ACL entries from a text string. This function parses the provided string and returns a collection of ACL entries.

### Signature
`pub fn from_str(s: &str) -> Result<Vec<AclEntry>>`

### Parameters
- **s** (&str) - The input string containing the ACL entries to be parsed.

### Returns
- **Result<Vec<AclEntry>>** - A Result type containing a vector of `AclEntry` on success, or an `io::Error` if the parsing fails.
```

--------------------------------

### to_writer function signature

Source: https://docs.rs/exacl/latest/exacl/fn.to_writer.html

The function signature for writing ACL entries to a writer.

```rust
pub fn to_writer<W: Write>(writer: W, entries: &[AclEntry]) -> Result<()>
```

--------------------------------

### Function Signature for getfacl

Source: https://docs.rs/exacl/latest/exacl/fn.getfacl.html

The signature for the getfacl function, which accepts a path and optional ACL options.

```rust
pub fn getfacl<P, O>(path: P, options: O) -> Result<Vec<AclEntry>>
where
    P: AsRef<Path>,
    O: Into<Option<AclOption>>,
```

--------------------------------

### Function signature for from_reader

Source: https://docs.rs/exacl/latest/exacl/fn.from_reader.html

The function signature for reading ACL entries from a generic reader.

```rust
pub fn from_reader<R: Read>(reader: R) -> Result<Vec<AclEntry>>
```

--------------------------------

### to_string

Source: https://docs.rs/exacl/latest/exacl/fn.to_string.html?search=std%3A%3Avec

Serializes a slice of AclEntry objects into a string.

```APIDOC
## fn to_string

### Description
Converts a slice of `AclEntry` objects into a string representation. This function follows the format defined by `to_writer`.

### Signature
`pub fn to_string(entries: &[AclEntry]) -> Result<String>`

### Parameters
- **entries** (&[AclEntry]) - Required - A slice of ACL entries to be converted to a string.

### Returns
- **Result<String>** - Returns a `String` containing the formatted ACL entries on success, or an `io::Error` on failure.
```

--------------------------------

### getfacl

Source: https://docs.rs/exacl/latest/exacl/fn.getfacl.html?search=std%3A%3Avec

Retrieves the access control list for a given path. The function supports platform-specific behavior for macOS and Linux, including handling of symlinks and default ACLs.

```APIDOC
## fn getfacl<P, O>(path: P, options: O) -> Result<Vec<AclEntry>>

### Description
Get access control list (ACL) for a file or directory. On success, returns a vector of `AclEntry` with all access control entries for the specified path.

### Parameters
- **path** (P: AsRef<Path>) - Required - The path to the file or directory.
- **options** (O: Into<Option<AclOption>>) - Required - Optional configuration for retrieving the ACL (e.g., SYMLINK_ACL, DEFAULT_ACL).

### Returns
- **Result<Vec<AclEntry>>** - A vector of ACL entries or an `io::Error` on failure.

### Example
```rust
use exacl::getfacl;

let entries = getfacl("./tmp/foo", None)?;
```
```

--------------------------------

### pub fn setfacl<P, O>(paths: &[P], entries: &[AclEntry], options: O) -> Result<()>

Source: https://docs.rs/exacl/latest/exacl/fn.setfacl.html

Sets the access control list for the specified paths using the provided access control entries. The function signature requires paths to be references to paths and options to be convertible to an AclOption.

```APIDOC
## setfacl

### Description
Sets the access control list (ACL) for specified files and directories. The semantics and permissions of the access control list depend on the underlying platform.

### Signature
`pub fn setfacl<P, O>(paths: &[P], entries: &[AclEntry], options: O) -> Result<()>`

### Parameters
- **paths** (&[P]) - A slice of paths (files or directories) to apply the ACL to.
- **entries** (&[AclEntry]) - A slice of AclEntry objects defining the access rules.
- **options** (O) - Optional configuration for the ACL operation, convertible to AclOption.

### Errors
Returns an `io::Error` if the operation fails.

### Examples

#### macOS Example
```rust
use exacl::{setfacl, AclEntry, Flag, Perm};

let entries = vec![
    AclEntry::allow_user("some_user", Perm::READ | Perm::WRITE, None),
    AclEntry::deny_group("some_group", Perm::WRITE, None)
];

setfacl(&["./tmp/foo"], &entries, None)?;
```

#### Linux Example
```rust
use exacl::{setfacl, AclEntry, Flag, Perm};

let entries = vec![
    AclEntry::allow_user("", Perm::READ | Perm::WRITE, None),
    AclEntry::allow_group("", Perm::READ, None),
    AclEntry::allow_other(Perm::empty(), None),
    AclEntry::allow_user("some_user", Perm::READ | Perm::WRITE, None),
];

setfacl(&["./tmp/foo"], &entries, None)?;
```
```

--------------------------------

### setfacl Function Signature

Source: https://docs.rs/exacl/latest/exacl/fn.setfacl.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The function signature for setting access control lists on files and directories.

```rust
pub fn setfacl<P, O>(
    paths: &[P],
    entries: &[AclEntry],
    options: O,
) -> Result<()>
where
    P: AsRef<Path>,
    O: Into<Option<AclOption>>,
```

--------------------------------

### from_reader

Source: https://docs.rs/exacl/latest/exacl/fn.from_reader.html?search=

Reads ACL entries from a text source provided by a reader.

```APIDOC
## pub fn from_reader<R: Read>(reader: R) -> Result<Vec<AclEntry>>

### Description
Reads ACL entries from text. Each ACL entry is presented on a separate line. A comment begins with # and proceeds to the end of the line. Within a field, leading or trailing white space are ignored.

### Parameters
- **reader** (R: Read) - Required - The reader source containing the ACL text.

### Returns
- **Result<Vec<AclEntry>>** - A vector of parsed ACL entries or an io::Error on failure.

### Supported Formats
- <allow>:<flags>:<kind>:<name>:<perms>
- <flags>:<kind>:<name>:<perms>
- <kind>:<name>:<perms>

### Example
```rust
use std::io::Cursor;
use exacl::from_reader;

let data = "allow::group:admin:read,write\nd:u:chip:rw";
let entries = from_reader(Cursor::new(data));
```
```

--------------------------------

### from_reader

Source: https://docs.rs/exacl/latest/exacl/fn.from_reader.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Reads ACL entries from a text source provided by a reader.

```APIDOC
## fn from_reader

### Description
Reads ACL entries from text. Each ACL entry is presented on a separate line. A comment begins with # and proceeds to the end of the line. Within a field, leading or trailing white space are ignored.

### Signature
`pub fn from_reader<R: Read>(reader: R) -> Result<Vec<AclEntry>>`

### Supported Formats
- <allow>:<flags>:<kind>:<name>:<perms>
- <flags>:<kind>:<name>:<perms>
- <kind>:<name>:<perms>

### Parameters
- **reader** (R: Read) - The source to read ACL entries from.

### Errors
Returns an io::Error on failure.
```

--------------------------------

### AclOption struct definition

Source: https://docs.rs/exacl/latest/exacl/struct.AclOption.html

The definition of the AclOption struct.

```rust
pub struct AclOption(/* private fields */);
```

--------------------------------

### to_writer

Source: https://docs.rs/exacl/latest/exacl/fn.to_writer.html?search=std%3A%3Avec

Writes ACL entries to a writer in a colon-separated text format.

```APIDOC
## fn to_writer<W: Write>(writer: W, entries: &[AclEntry]) -> Result<()>

### Description
Writes ACL entries to text. Each ACL entry is printed on a separate line with fields separated by colons.

### Parameters
- **writer** (W: Write) - The destination to write the ACL entries.
- **entries** (&[AclEntry]) - A slice of ACL entries to be serialized.

### Format
<allow>:<flags>:<kind>:<name>:<perms>

### Errors
Returns an io::Error on failure.
```

--------------------------------

### ACL Entry Format Specification

Source: https://docs.rs/exacl/latest/exacl/fn.from_reader.html?search=std%3A%3Avec

The supported text formats for defining ACL entries.

```text
  Three allowed forms:

  <allow>:<flags>:<kind>:<name>:<perms>
  <flags>:<kind>:<name>:<perms>
  <kind>:<name>:<perms>

  <allow> - one of "allow" or "deny"
  <flags> - comma-separated list of flags
  <kind>  - one of "user", "group", "other", "mask", "unknown"
  <name>  - user/group name (decimal id accepted)
  <perms> - comma-separated list of permissions
```

--------------------------------

### getfacl

Source: https://docs.rs/exacl/latest/exacl/fn.getfacl.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the access control list (ACL) for a specified file or directory path. The function returns a vector of AclEntry objects, with behavior varying based on the underlying operating system.

```APIDOC
## getfacl(path, options)

### Description
Retrieves the access control list (ACL) for a file or directory. On success, it returns a vector of `AclEntry` objects representing the access control entries.

### Signature
`pub fn getfacl<P, O>(path: P, options: O) -> Result<Vec<AclEntry>>`

### Parameters
- **path** (AsRef<Path>) - The path to the file or directory.
- **options** (Into<Option<AclOption>>) - Optional configuration for the ACL retrieval (e.g., SYMLINK_ACL, DEFAULT_ACL).

### Errors
Returns an `io::Error` if the operation fails.

### Example
```rust
use exacl::getfacl;

let entries = getfacl("./tmp/foo", None)?;
```
```

--------------------------------

### from_mode function signature

Source: https://docs.rs/exacl/latest/exacl/fn.from_mode.html

The function signature for converting mode bits to a vector of ACL entries.

```rust
pub fn from_mode(mode: u32) -> Vec<AclEntry>
```

--------------------------------

### setfacl

Source: https://docs.rs/exacl/latest/exacl/fn.setfacl.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Sets the access control list (ACL) for the specified paths using the provided access control entries. The function signature is `pub fn setfacl<P, O>(paths: &[P], entries: &[AclEntry], options: O) -> Result<()> where P: AsRef<Path>, O: Into<Option<AclOption>>`.

```APIDOC
## setfacl

### Description
Sets the access control list (ACL) for specified files and directories. The semantics and permissions depend on the underlying platform.

### Signature
`pub fn setfacl<P, O>(paths: &[P], entries: &[AclEntry], options: O) -> Result<()> where P: AsRef<Path>, O: Into<Option<AclOption>>`

### Parameters
- **paths** (&[P]) - Required - A slice of paths to apply the ACL to.
- **entries** (&[AclEntry]) - Required - A slice of access control entries to apply.
- **options** (O) - Required - Optional configuration options for the ACL operation.

### Errors
Returns an `io::Error` on failure.
```

--------------------------------

### AclEntry Struct Definition

Source: https://docs.rs/exacl/latest/exacl/struct.AclEntry.html?search=u32+-%3E+bool

The primary structure representing an ACL entry.

```rust
pub struct AclEntry {
    pub kind: AclEntryKind,
    pub name: String,
    pub perms: Perm,
    pub flags: Flag,
    pub allow: bool,
}
```

--------------------------------

### Flag struct definition

Source: https://docs.rs/exacl/latest/exacl/struct.Flag.html

The primary structure used to represent ACL entry inheritance flags.

```rust
pub struct Flag(/* private fields */);
```

--------------------------------

### fn setfacl

Source: https://docs.rs/exacl/latest/exacl/fn.setfacl.html?search=

Sets the access control list (ACL) for the specified paths using the provided access control entries. The function signature is: pub fn setfacl<P, O>(paths: &[P], entries: &[AclEntry], options: O) -> Result<()> where P: AsRef<Path>, O: Into<Option<AclOption>>.

```APIDOC
## fn setfacl(paths, entries, options)

### Description
Sets access control list (ACL) for specified files and directories. The semantics and permissions of the access control list depend on the underlying platform.

### Parameters
- **paths** (&[P]) - Required - A slice of paths to apply the ACL to.
- **entries** (&[AclEntry]) - Required - A slice of AclEntry objects defining the permissions.
- **options** (O) - Optional - Configuration options for the ACL operation.

### Errors
Returns an io::Error on failure.
```

--------------------------------

### fn setfacl

Source: https://docs.rs/exacl/latest/exacl/fn.setfacl.html?search=std%3A%3Avec

Sets the access control list (ACL) for the specified paths using the given access control entries. The function signature is: pub fn setfacl<P, O>(paths: &[P], entries: &[AclEntry], options: O) -> Result<()> where P: AsRef<Path>, O: Into<Option<AclOption>>.

```APIDOC
## fn setfacl

### Description
Sets the access control list (ACL) for specified files and directories. The semantics and permissions of the access control list depend on the underlying platform.

### Signature
`pub fn setfacl<P, O>(paths: &[P], entries: &[AclEntry], options: O) -> Result<()>`

### Parameters
- **paths** (&[P]) - A slice of paths (files or directories) to apply the ACL to.
- **entries** (&[AclEntry]) - A slice of access control entries to apply.
- **options** (O) - Optional configuration options (AclOption).

### Errors
Returns an `io::Error` on failure.

### Examples
#### macOS
```rust
use exacl::{setfacl, AclEntry, Flag, Perm};
let entries = vec![
    AclEntry::allow_user("some_user", Perm::READ | Perm::WRITE, None),
    AclEntry::deny_group("some_group", Perm::WRITE, None)
];
setfacl(&["./tmp/foo"], &entries, None)?;
```

#### Linux
```rust
use exacl::{setfacl, AclEntry, Flag, Perm};
let entries = vec![
    AclEntry::allow_user("", Perm::READ | Perm::WRITE, None),
    AclEntry::allow_group("", Perm::READ, None),
    AclEntry::allow_other(Perm::empty(), None),
    AclEntry::allow_user("some_user", Perm::READ | Perm::WRITE, None),
];
setfacl(&["./tmp/foo"], &entries, None)?;
```
```

--------------------------------

### setfacl

Source: https://docs.rs/exacl/latest/exacl/fn.setfacl.html?search=u32+-%3E+bool

Sets the access control list for the specified paths using the provided access control entries.

```APIDOC
## setfacl

### Description
Sets the access control list (ACL) for specified files and directories. The semantics and permissions of the access control list depend on the underlying platform.

### Signature
`pub fn setfacl<P, O>(paths: &[P], entries: &[AclEntry], options: O) -> Result<()>`

### Parameters
- **paths** (&[P]) - A slice of paths (types implementing AsRef<Path>) to apply the ACL to.
- **entries** (&[AclEntry]) - A slice of AclEntry objects defining the permissions.
- **options** (O) - Options (types implementing Into<Option<AclOption>>) to configure the operation.

### Errors
Returns an `io::Error` on failure.
```

--------------------------------

### Define AclEntryKind Enum

Source: https://docs.rs/exacl/latest/exacl/enum.AclEntryKind.html?search=

The AclEntryKind enum represents the type of an ACL entry.

```rust
pub enum AclEntryKind {
    User,
    Group,
    Mask,
    Other,
    Everyone,
    Unknown,
}
```
Tokens:
Raw