Struct File 

pub struct File<'f, 'a: 'f> { /* private fields */ }

An open file, held as a capability.

Why it borrows the Fs handle

A File and its Fs speak to the same service on the same endpoint, so they must share ONE correlation tag counter - two counters can mint the same tag for two exchanges in flight, and the result is not a loud rejection but a stale reply silently accepted as the current answer. Holding &mut Fs makes that structural: the borrow checker will not let the two be used at once, so there is no way to spell the bug.

The cost is that one Fs handle opens one file at a time. To hold two, thread the counter yourself with Fs::from_tag and Fs::tag.

Implementations

impl<'f, 'a: 'f> File<'f, 'a>

pub fn rights(&self) -> u8

The rights this capability CARRIES - cap::READ and cap::WRITE - as the kernel reported them when the file was opened.

Not necessarily what you asked Fs::open for: fs narrows a sealed file to read-only rather than mint a cap it cannot honour (7.3 - rights narrow), and cap::APPEND is a request to fs, never a kernel right, so it is not here. (Until 2026-10-10 this was the mask asked for, and a close under it was refused - backlog/fixed/80 G2.)

pub fn take_held(&mut self) -> Option<Message>

Take one message that arrived during an operation and was NOT the reply.

Call this in a loop until it returns None after every operation, if your task serves clients. These are real requests from them; the library held them rather than dropping them, but only you can answer them.

Returns None for a task that serves nobody, always.

pub fn read_at(&mut self, offset: u64, buf: &mut [u8]) -> Result<usize, Error>

Read from the file through the capability.

Returns how many bytes landed in buf, which may be fewer than asked for at end of file. One invocation moves at most IO_CHUNK bytes; call again with a later offset for more.

Blocks up to call::DEFAULT_SECS. Authority: this capability’s READ right, which the KERNEL checks before fs is reached.

Errors

• Error::PermissionDenied - this capability does not carry READ.
• Error::Revoked - the file was deleted or closed, or fs restarted: the capability is finished, and the answer is to re-open rather than to retry.
• A read changes nothing, so every no-answer error here is safe to retry.

pub fn write_at(&mut self, offset: u64, data: &[u8]) -> Result<(), Error>

Write to the file through the capability.

Blocks up to call::DEFAULT_SECS. Authority: this capability’s WRITE right.

Errors

• Error::PermissionDenied - no WRITE, or an APPEND-only capability was asked to write below the furthest offset it has already written.
• Error::Failed - offset is not a multiple of 508, or the write runs past the file’s extent; as for Fs::write_at, fs does not grow a file here.
• Error::InvalidInput - more than IO_CHUNK bytes in one call. Nothing is written; split it rather than assuming a partial write happened.
• A write MUTATES. Do not retry on Error::OutcomeUnknown without first reading back what is actually there - see Error::retry_is_safe.

pub fn size(&mut self) -> Result<u64, Error>

The file’s current size in bytes.

Blocks up to call::DEFAULT_SECS. Authority: this capability’s READ right.

pub fn close(self) -> Result<(), Error>

Close the file, revoking this capability and every copy of it.

Consumes the handle, and returns what the service said. Dropping a File without calling this also closes it, but a Drop cannot report a failure - so close explicitly wherever the outcome matters.

The close is invoked under a right the capability carries (rights), so a read-only, a narrowed or an APPEND-only file closes like any other.

Trait Implementations

impl<'f, 'a: 'f> Drop for File<'f, 'a>

fn drop(&mut self)

Closes the file if close was not called.

fs keeps a FIXED table of open resources, so leaking one is not merely untidy - enough leaks and nothing can be opened at all. That is why this closes rather than merely warning.

A Drop cannot return a Result, so a close that FAILS here is invisible. That is the reason close exists and is worth calling wherever the outcome matters.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.