### Implement a minimal Casper service for getuid(2)

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Provides an example of a minimal Casper service that calls getuid(2). This demonstrates the `casper::Service` trait and the `casper::service!` macro for registering services.

```rust
// examples/getuid.rs — a minimal Casper service that calls getuid(2)
use std::{ffi::CStr, io};
use capsicum::casper::{self, Casper, NvFlag, NvList, ServiceRegisterFlags};
use libc::uid_t;

struct CapUid {}
impl casper::Service for CapUid {
    const SERVICE_NAME: &'static CStr = c"getuid";

    fn cmd(
        cmd: &str,
        limits: Option<&NvList>,
        _nvin: Option<&mut NvList>,
        nvout: &mut NvList,
    ) -> io::Result<()> {
        assert_eq!(cmd, "getuid");
        if limits.is_some() {
            return Err(io::Error::from_raw_os_error(libc::ENOTCAPABLE));
        }
        let uid = unsafe { libc::getuid() };
        nvout.insert_number(c"uid", uid).unwrap();
        Ok(())
    }

    fn limit(_old: Option<&NvList>, _new: Option<&NvList>) -> io::Result<()> {
        Ok(())
    }
}

// Registers the service and generates `CapAgent` struct + `Casper::uid()` method.
casper::service!(pub CapUid, CapAgent, uid, ServiceRegisterFlags::NONE);

impl CapAgent {
    pub fn uid(&mut self) -> io::Result<uid_t> {
        let mut invl = NvList::new(NvFlag::None).unwrap();
        invl.insert_string(c"cmd", c"getuid").unwrap();
        let onvl = self.xfer_nvlist(invl)?;
        Ok(onvl.get_number(c"uid").unwrap().unwrap() as uid_t)
    }
}

fn main() {
    // Must be called while single-threaded.
    let mut casper = unsafe { Casper::new().unwrap() };

    // Enter capability mode AFTER initialising Casper.
    capsicum::enter().unwrap();

    let mut agent = casper.uid().unwrap();
    println!("UID = {}", agent.uid().unwrap());
}
```

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

### casper::service_connection!

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Generates a connection struct and an accessor on `Casper` for services that live in a separate crate or are provided by the OS. This example shows how to connect to the system-supplied group database service.

```APIDOC
## `casper::service_connection!` — Connect to an existing Casper service

`service_connection!` generates a connection struct and an accessor on `Casper` for services that live in a separate crate or are provided by the OS (e.g., `system.grp`, `system.dns`).

```rust
use capsicum::casper::{self, Casper};

// Connect to the system-supplied group database service.
casper::service_connection!(
    pub CapGroupAgent,
    c"system.grp",
    group
);

fn main() {
    let mut casper = unsafe { Casper::new().unwrap() };
    capsicum::enter().unwrap();

    // Opens a channel to the "system.grp" Casper service.
    let mut grp_agent = casper.group().unwrap();

    // Use limit_get / limit_set to further restrict the service.
    let limits = grp_agent.limit_get().unwrap();
    println!("current limits: {:?}", limits);
}
```
```

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

### Enter Capability Mode in Rust

Source: https://github.com/dlrobertson/capsicum-rs/blob/main/README.md

Demonstrates entering capability mode and verifying sandboxing. File operations attempted after entering capability mode should fail if not previously allowed.

```rust
    use capsicum::{enter, sandboxed};
    use std::fs::File;
    use std::io::Read;

    let mut ok_file = File::open("/tmp/foo").unwrap();
    let mut s = String::new();

    enter().expect("enter failed!");
    assert!(sandboxed(), "application is not sandboxed!");

    match File::create("/tmp/cant_touch_this") {
        Ok(_) => panic!("application is not properly sandboxed!"),
        Err(e) => println!("properly sandboxed: {:?}", e)
    }

    match ok_file.read_to_string(&mut s) {
        Ok(_) => println!("This is okay since we opened the descriptor before sandboxing"),
        Err(_) => panic!("application is not properly sandboxed!")
    }
```

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

### Compose File Rights Sets with merge, deny, remove

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Demonstrates how to union, deny, and remove file rights from a FileRights set. Ensure rights are managed carefully to avoid unintended access.

```rust
use capsicum::{FileRights, Right};

let mut base = FileRights::new();
base.allow(Right::Read).allow(Right::Write).allow(Right::Seek);

// Build an addendum and merge it in.
let mut extra = FileRights::new();
extra.allow(Right::Fstat);
base.merge(&extra).unwrap();
assert!(base.is_set(Right::Fstat));

// Remove write permission.
base.deny(Right::Write);
assert!(!base.is_set(Right::Write));

// Remove all rights that are in `extra`.
base.remove(&extra).unwrap();
assert!(!base.is_set(Right::Fstat));
```

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

### Clone and Build capsicum-rs

Source: https://github.com/dlrobertson/capsicum-rs/blob/main/README.md

Standard procedure to clone the repository and build the project using Cargo.

```bash
git clone https://github.com/danlrobertson/capsicum-rs
cd capsicum-rs
cargo build
```

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

### Connect to Casper Service with `service_connection!`

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Generates a connection struct and accessor for services in separate crates or provided by the OS. Use this to establish a connection to a specific Casper service like `system.grp`.

```rust
use capsicum::casper::{self, Casper};

// Connect to the system-supplied group database service.
casper::service_connection!(
    pub CapGroupAgent,
    c"system.grp",
    group
);

fn main() {
    let mut casper = unsafe { Casper::new().unwrap() };
    capsicum::enter().unwrap();

    // Opens a channel to the "system.grp" Casper service.
    let mut grp_agent = casper.group().unwrap();

    // Use limit_get / limit_set to further restrict the service.
    let limits = grp_agent.limit_get().unwrap();
    println!("current limits: {:?}", limits);
}
```

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

### Limit File Rights in Rust

Source: https://github.com/dlrobertson/capsicum-rs/blob/main/README.md

Shows how to create a set of capabilities for a file descriptor, including conditionally adding read rights, and then limiting the file's rights.

```rust
    use capsicum::{CapRights, Right, RightsBuilder};
    use std::fs::File;
    use std::io::Read;

    let x = rand::random::<bool>();
    
    let mut ok_file = File::open("/tmp/foo").unwrap();
    let mut s = String::new();
    
    let mut builder = RightsBuilder::new(Right::Seek);
    
    if x {
        builder.add(Right::Read);
    }

    let rights = builder.finalize().unwrap();

    rights.limit(&ok_file).unwrap();
    
    match ok_file.read_to_string(&mut s) {
        Ok(_) if x => println!("Allowed reading: x = {} ", x),
        Err(_) if !x => println!("Did not allow reading: x = {}", x),
        _ => panic!("Not properly sandboxed"),
    }
```

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

### FileRights Manipulation

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Demonstrates how to manipulate FileRights sets using merge(), deny(), and remove() methods for managing file access permissions.

```APIDOC
## `capsicum::FileRights::merge` / `deny` / `remove` — Compose rights sets

`merge()` unions two `FileRights` sets in place. `deny()` removes a single right. `remove()` subtracts an entire `FileRights` set.

```rust
use capsicum::{FileRights, Right};

let mut base = FileRights::new();
base.allow(Right::Read).allow(Right::Write).allow(Right::Seek);

// Build an addendum and merge it in.
let mut extra = FileRights::new();
extra.allow(Right::Fstat);
base.merge(&extra).unwrap();
assert!(base.is_set(Right::Fstat));

// Remove write permission.
base.deny(Right::Write);
assert!(!base.is_set(Right::Write));

// Remove all rights that are in `extra`.
base.remove(&extra).unwrap();
assert!(!base.is_set(Right::Fstat));
```
```

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

### Restrict ioctl(2) commands with IoctlsBuilder and IoctlRights

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Demonstrates restricting ioctl(2) commands by building an allowlist of command codes. This is useful for limiting the scope of device interactions.

```rust
use std::mem;
use std::os::unix::io::AsRawFd;
use libc::{c_int, u_long};
use nix::{ioctl_read, request_code_read};
use nix::errno::Errno;
use nix::sys::socket::{AddressFamily, SockFlag, SockType, socketpair};
use capsicum::{CapRights, IoctlsBuilder};

const FIONREAD: u_long = request_code_read!(b'f', 127, mem::size_of::<c_int>());
ioctl_read!(fionread, b'f', 127, c_int);
ioctl_read!(fionwrite, b'f', 119, c_int);

let (fd1, _fd2) = socketpair(
    AddressFamily::Unix,
    SockType::Stream,
    None,
    SockFlag::empty(),
).unwrap();

// Allow only FIONREAD; deny FIONWRITE.
IoctlsBuilder::new()
    .allow(FIONREAD)
    .finalize()
    .limit(&fd1)
    .unwrap();

capsicum::enter().unwrap();

let mut n: c_int = 0;
unsafe { fionread(fd1.as_raw_fd(), &mut n as *mut c_int) }.unwrap();

let err = unsafe { fionwrite(fd1.as_raw_fd(), &mut n as *mut c_int) };
assert_eq!(err, Err(Errno::ENOTCAPABLE));
```

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

### Enter Capability Mode with Capsicum

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Transitions the calling process into capability mode. Resources must be opened before entering the sandbox. Opening new paths after entering fails with ECAPMODE.

```rust
use capsicum::{enter, sandboxed};
use std::fs::File;
use std::io::Read;

// Open resources BEFORE entering capability mode.
let mut file = File::open("/etc/passwd").unwrap();
let mut contents = String::new();

// Enter the sandbox — returns io::Error on failure.
enter().expect("cap_enter failed");

// Verify we are sandboxed.
assert!(sandboxed(), "process should be sandboxed");

// Attempting to open a new path now fails with ECAPMODE.
assert!(File::open("/etc/hosts").is_err());

// Previously opened descriptors still work.
file.read_to_string(&mut contents).unwrap();
println!("read {} bytes from pre-opened fd", contents.len());

```

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

### Casper Privileged Helper Services

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Introduces the Casper feature for creating and managing privileged helper services, including service registration and inter-process communication.

```APIDOC
## Casper — Privileged helper services (`casper` feature)

The `casper` feature exposes `Casper` and the `service!` / `service_connection!` macros. `Casper::new()` forks a helper process before the main process enters capability mode. Custom services implement the `casper::Service` trait; the `service!` macro wires up the C-level callbacks and generates an accessor method on `Casper`.

```rust
// examples/getuid.rs — a minimal Casper service that calls getuid(2)
use std::{ffi::CStr, io};
use capsicum::casper::{self, Casper, NvFlag, NvList, ServiceRegisterFlags};
use libc::uid_t;

struct CapUid {}
impl casper::Service for CapUid {
    const SERVICE_NAME: &'static CStr = c"getuid";

    fn cmd(
        cmd: &str,
        limits: Option<&NvList>,
        _nvin: Option<&mut NvList>,
        nvout: &mut NvList,
    ) -> io::Result<()> {
        assert_eq!(cmd, "getuid");
        if limits.is_some() {
            return Err(io::Error::from_raw_os_error(libc::ENOTCAPABLE));
        }
        let uid = unsafe { libc::getuid() };
        nvout.insert_number(c"uid", uid).unwrap();
        Ok(())
    }

    fn limit(_old: Option<&NvList>, _new: Option<&NvList>) -> io::Result<()> {
        Ok(())
    }
}

// Registers the service and generates `CapAgent` struct + `Casper::uid()` method.
casper::service!(pub CapUid, CapAgent, uid, ServiceRegisterFlags::NONE);

impl CapAgent {
    pub fn uid(&mut self) -> io::Result<uid_t> {
        let mut invl = NvList::new(NvFlag::None).unwrap();
        invl.insert_string(c"cmd", c"getuid").unwrap();
        let onvl = self.xfer_nvlist(invl)?;
        Ok(onvl.get_number(c"uid").unwrap().unwrap() as uid_t)
    }
}

fn main() {
    // Must be called while single-threaded.
    let mut casper = unsafe { Casper::new().unwrap() };

    // Enter capability mode AFTER initialising Casper.
    capsicum::enter().unwrap();

    let mut agent = casper.uid().unwrap();
    println!("UID = {}", agent.uid().unwrap());
}
```
```

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

### capsicum::enter — Enter capability mode

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Transitions the calling process into capability mode. After this call succeeds, the process can no longer open new paths, make new network connections, or otherwise access global namespaces. The call is irreversible for the lifetime of the process.

```APIDOC
## `capsicum::enter` — Enter capability mode

### Description
Transitions the calling process into capability mode. After this call succeeds, the process can no longer open new paths, make new network connections, or otherwise access global namespaces. The call is irreversible for the lifetime of the process.

### Method
Rust function call

### Endpoint
N/A (Rust function)

### Parameters
None

### Request Example
```rust
use capsicum::{enter, sandboxed};
use std::fs::File;
use std::io::Read;

// Open resources BEFORE entering capability mode.
let mut file = File::open("/etc/passwd").unwrap();
let mut contents = String::new();

// Enter the sandbox — returns io::Error on failure.
enter().expect("cap_enter failed");

// Verify we are sandboxed.
assert!(sandboxed(), "process should be sandboxed");

// Attempting to open a new path now fails with ECAPMODE.
assert!(File::open("/etc/hosts").is_err());

// Previously opened descriptors still work.
file.read_to_string(&mut contents).unwrap();
println!("read {} bytes from pre-opened fd", contents.len());
```

### Response
#### Success Response
No explicit return value on success, but the process enters capability mode.

#### Response Example
N/A
```

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

### IoctlsBuilder and IoctlRights for ioctl(2) Commands

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Details how to use IoctlsBuilder to create an allowlist of ioctl command codes, producing an IoctlRights value for descriptor application.

```APIDOC
## `capsicum::IoctlsBuilder` / `IoctlRights` — Restrict `ioctl(2)` commands

`IoctlsBuilder` collects an allowlist of `ioctl` command codes; `.finalize()` produces an `IoctlRights` value that can be applied to a descriptor.

```rust
use std::mem;
use std::os::unix::io::AsRawFd;
use libc::{c_int, u_long};
use nix::{ioctl_read, request_code_read};
use nix::errno::Errno;
use nix::sys::socket::{AddressFamily, SockFlag, SockType, socketpair};
use capsicum::{CapRights, IoctlsBuilder};

const FIONREAD: u_long = request_code_read!(b'f', 127, mem::size_of::<c_int>());
ioctl_read!(fionread, b'f', 127, c_int);
ioctl_read!(fionwrite, b'f', 119, c_int);

let (fd1, _fd2) = socketpair(
    AddressFamily::Unix,
    SockType::Stream,
    None,
    SockFlag::empty(),
).unwrap();

// Allow only FIONREAD; deny FIONWRITE.
IoctlsBuilder::new()
    .allow(FIONREAD)
    .finalize()
    .limit(&fd1)
    .unwrap();

capsicum::enter().unwrap();

let mut n: c_int = 0;
unsafe { fionread(fd1.as_raw_fd(), &mut n as *mut c_int) }.unwrap();

let err = unsafe { fionwrite(fd1.as_raw_fd(), &mut n as *mut c_int) };
assert_eq!(err, Err(Errno::ENOTCAPABLE));
```
```

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

### FcntlRights for fcntl(2) Commands

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Explains how to use FcntlRights to restrict which fcntl(2) commands can be issued on a descriptor in capability mode.

```APIDOC
## `capsicum::FcntlRights` — Restrict `fcntl(2)` commands

`FcntlRights` limits which `fcntl(2)` commands (`F_GETFL`, `F_SETFL`, `F_GETOWN`, `F_SETOWN`) may be issued on a descriptor in capability mode.

```rust
use std::os::unix::io::AsRawFd;
use capsicum::{CapRights, Fcntl, FcntlRights};
use nix::fcntl::{FcntlArg, OFlag, fcntl};
use nix::errno::Errno;
use tempfile::tempfile;

let file = tempfile().unwrap();

// Allow F_GETFL but not F_SETFL.
FcntlRights::new()
    .allow(Fcntl::GetFL)
    .limit(&file)
    .unwrap();

capsicum::enter().unwrap();

// F_GETFL succeeds.
fcntl(file.as_raw_fd(), FcntlArg::F_GETFL).unwrap();

// F_SETFL fails with ENOTCAPABLE.
let err = fcntl(file.as_raw_fd(), FcntlArg::F_SETFL(OFlag::O_NONBLOCK));
assert_eq!(err, Err(Errno::ENOTCAPABLE));
```
```

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

### Restrict fcntl(2) commands with FcntlRights

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Shows how to limit which fcntl(2) commands can be issued on a descriptor in capability mode. Use this to enforce fine-grained control over descriptor operations.

```rust
use std::os::unix::io::AsRawFd;
use capsicum::{CapRights, Fcntl, FcntlRights};
use nix::fcntl::{FcntlArg, OFlag, fcntl};
use nix::errno::Errno;
use tempfile::tempfile;

let file = tempfile().unwrap();

// Allow F_GETFL but not F_SETFL.
FcntlRights::new()
    .allow(Fcntl::GetFL)
    .limit(&file)
    .unwrap();

capsicum::enter().unwrap();

// F_GETFL succeeds.
fcntl(file.as_raw_fd(), FcntlArg::F_GETFL).unwrap();

// F_SETFL fails with ENOTCAPABLE.
let err = fcntl(file.as_raw_fd(), FcntlArg::F_SETFL(OFlag::O_NONBLOCK));
assert_eq!(err, Err(Errno::ENOTCAPABLE));
```

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

### Inspect File Descriptor Rights with FileRights::from_file

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Retrieves the current `FileRights` assigned to a file descriptor. Useful for auditing or cloning existing rights.

```rust
use capsicum::{CapRights, FileRights, Right};
use tempfile::tempfile;

let file = tempfile().unwrap();

let mut rights = FileRights::new();
rights.allow(Right::Read);
rights.allow(Right::Write);
rights.limit(&file).unwrap();

// Read the effective rights back from the kernel.
let actual = FileRights::from_file(&file).unwrap();
assert!(actual.is_set(Right::Read));
assert!(actual.is_set(Right::Write));
assert!(!actual.is_set(Right::Fexecve));

```

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

### Query Sandbox Status with Capsicum

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Checks if the current process is in capability mode. `get_mode()` also returns `false` if the kernel lacks Capsicum support.

```rust
use capsicum::{sandboxed, get_mode};

// Before entering capability mode:
assert!(!sandboxed());
assert_eq!(get_mode().unwrap(), false);

capsicum::enter().unwrap();

// After entering capability mode:
assert!(sandboxed());
assert_eq!(get_mode().unwrap(), true);

```

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

### capsicum::sandboxed / capsicum::get_mode — Query sandbox status

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Query sandbox status. `sandboxed()` returns `true` if the process is currently in capability mode. `get_mode()` does the same but propagates a kernel error (`ENOSYS`) if the kernel was compiled without capsicum support.

```APIDOC
## `capsicum::sandboxed` / `capsicum::get_mode` — Query sandbox status

### Description
Query sandbox status. `sandboxed()` returns `true` if the process is currently in capability mode. `get_mode()` does the same but propagates a kernel error (`ENOSYS`) if the kernel was compiled without capsicum support.

### Method
Rust function calls

### Endpoint
N/A (Rust functions)

### Parameters
None

### Request Example
```rust
use capsicum::{sandboxed, get_mode};

// Before entering capability mode:
assert!(!sandboxed());
assert_eq!(get_mode().unwrap(), false);

capsicum::enter().unwrap();

// After entering capability mode:
assert!(sandboxed());
assert_eq!(get_mode().unwrap(), true);
```

### Response
#### Success Response
- **bool**: `true` if sandboxed, `false` otherwise.

#### Response Example
```rust
assert_eq!(get_mode().unwrap(), false);
```
```

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

### capsicum::FileRights — Restrict file descriptor capabilities

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

`FileRights` is a `Copy + Clone` bitset of [`Right`] values. Calling `.limit()` on a file descriptor narrows that descriptor's allowed operations permanently. Subsequent attempts to exercise a revoked right return `ENOTCAPABLE`.

```APIDOC
## `capsicum::FileRights` — Restrict file descriptor capabilities

### Description
`FileRights` is a `Copy + Clone` bitset of [`Right`] values. Calling `.limit()` on a file descriptor narrows that descriptor's allowed operations permanently. Subsequent attempts to exercise a revoked right return `ENOTCAPABLE`.

### Method
Rust method calls

### Endpoint
N/A (Rust methods)

### Parameters
None

### Request Example
```rust
use std::io::{Read, Write};
use capsicum::{CapRights, FileRights, Right};
use tempfile::tempfile;

let mut file = tempfile().unwrap();

// Allow only reading; deny writing.
FileRights::new()
    .allow(Right::Read)
    .allow(Right::Seek)
    .limit(&file)
    .unwrap();

capsicum::enter().unwrap();

// Read succeeds.
let mut buf = vec![0u8; 8];
file.read(&mut buf).unwrap();

// Write returns ENOTCAPABLE.
let err = file.write(b"hello").unwrap_err();
assert_eq!(err.raw_os_error(), Some(libc::ENOTCAPABLE));
```

### Response
#### Success Response
No explicit return value on success, but the file descriptor's rights are limited.

#### Response Example
N/A
```

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

### capsicum::FileRights::from_file — Inspect current rights on a descriptor

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Retrieves the `FileRights` currently assigned to a file descriptor. Useful for auditing or cloning the rights of an existing descriptor.

```APIDOC
## `capsicum::FileRights::from_file` — Inspect current rights on a descriptor

### Description
Retrieves the `FileRights` currently assigned to a file descriptor. Useful for auditing or cloning the rights of an existing descriptor.

### Method
Rust function call

### Endpoint
N/A (Rust function)

### Parameters
None

### Request Example
```rust
use capsicum::{CapRights, FileRights, Right};
use tempfile::tempfile;

let file = tempfile().unwrap();

let mut rights = FileRights::new();
rights.allow(Right::Read);
rights.allow(Right::Write);
rights.limit(&file).unwrap();

// Read the effective rights back from the kernel.
let actual = FileRights::from_file(&file).unwrap();
assert!(actual.is_set(Right::Read));
assert!(actual.is_set(Right::Write));
assert!(!actual.is_set(Right::Fexecve));
```

### Response
#### Success Response
- **FileRights**: The current rights assigned to the file descriptor.

#### Response Example
```rust
let actual = FileRights::from_file(&file).unwrap();
assert!(actual.is_set(Right::Read));
```
```

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

### Check Rights Set Membership with FileRights::contains / is_set

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Checks if one `FileRights` set is a subset of another (`contains`), or if a single `Right` is present (`is_set`).

```rust
use capsicum::{FileRights, Right};

let mut broad = FileRights::new();
broad.allow(Right::Read);
broad.allow(Right::Write);
broad.allow(Right::Seek);

let mut narrow = FileRights::new();
narrow.allow(Right::Read);

// narrow ⊆ broad
assert!(broad.contains(&narrow));
// broad ⊄ narrow
assert!(!narrow.contains(&broad));

assert!(broad.is_set(Right::Write));
assert!(!narrow.is_set(Right::Write));

```

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

### Restrict File Descriptor Capabilities with FileRights

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

Limits a file descriptor's allowed operations permanently. Revoked operations will return `ENOTCAPABLE`.

```rust
use std::io::{Read, Write};
use capsicum::{CapRights, FileRights, Right};
use tempfile::tempfile;

let mut file = tempfile().unwrap();

// Allow only reading; deny writing.
FileRights::new()
    .allow(Right::Read)
    .allow(Right::Seek)
    .limit(&file)
    .unwrap();

capsicum::enter().unwrap();

// Read succeeds.
let mut buf = vec![0u8; 8];
file.read(&mut buf).unwrap();

// Write returns ENOTCAPABLE.
let err = file.write(b"hello").unwrap_err();
assert_eq!(err.raw_os_error(), Some(libc::ENOTCAPABLE));

```

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

### capsicum::FileRights::contains / is_set — Inspect a rights set

Source: https://context7.com/dlrobertson/capsicum-rs/llms.txt

`contains()` checks whether one `FileRights` is a subset of another. `is_set()` checks a single [`Right`].

```APIDOC
## `capsicum::FileRights::contains` / `is_set` — Inspect a rights set

### Description
`contains()` checks whether one `FileRights` is a subset of another. `is_set()` checks a single [`Right`].

### Method
Rust method calls

### Endpoint
N/A (Rust methods)

### Parameters
None

### Request Example
```rust
use capsicum::{FileRights, Right};

let mut broad = FileRights::new();
broad.allow(Right::Read);
broad.allow(Right::Write);
broad.allow(Right::Seek);

let mut narrow = FileRights::new();
narrow.allow(Right::Read);

// narrow ⊆ broad
assert!(broad.contains(&narrow));
// broad ⊄ narrow
assert!(!narrow.contains(&broad));

assert!(broad.is_set(Right::Write));
assert!(!narrow.is_set(Right::Write));
```

### Response
#### Success Response
- **bool**: `true` if the condition is met, `false` otherwise.

#### Response Example
```rust
assert!(broad.contains(&narrow));
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.