Crate godspeed 

The GodspeedOS standard library.

Small, typed wrappers over the mechanisms GodspeedOS already has, so that writing a program does not start with learning a wire protocol.

The whole of it

use godspeed::{fs, io, ipc, ServiceContext};

#[no_mangle]
pub extern "C" fn service_main(ctx: ServiceContext) -> ! {
    let mut fs = fs::Fs::new(&ctx);
    let mut buf = [0u8; 4096];

    match fs.read_into("/data/hello.txt", &mut buf) {
        Ok(n)  => io::println(&ctx, core::str::from_utf8(&buf[..n]).unwrap_or("<not utf-8>")),
        Err(e) => io::report(&ctx, "read", e),
    }
    ipc::park(&ctx) // finished: hold still, using no CPU (see "Why `service_main`" below)
}

What this library will not do for you

It does not grant authority. Every entry point takes a &ServiceContext, because that is where authority lives. fs::Fs::new(&ctx) is a convenience, not a capability: a task whose spawn request never named the filesystem as a peer (CLAUDE.md 13.6), and that holds no ACQUIRE_ANY, gets Error::Unreachable from it, the same as for any peer it cannot reach. There is no global, no ambient handle, and no print! that finds a stdout on its own - a global would be ambient authority wearing a familiar name.

It does not hide failure. In particular it does not hide the difference between “the request never left” and “no answer came back”, because those demand opposite responses and collapsing them is how a retry becomes a second delete. Error::retry_is_safe is the answer in one call.

It does not pretend there is a heap. There is not, deliberately (CLAUDE.md §26.6.1), so nothing here returns an allocated String or Vec. Callers own their buffers and the bound is readable in the source. Making this look like Rust’s std would mean trading the architecture for a familiar shape, which is the one thing this library is not for.

Why service_main and not fn main

Because GodspeedOS has no terminating task yet. Every runnable thing is a service, entered at service_main(ctx) -> !, and of the 54 syscalls the only one that ends a task is Kill - which kills by name and is gated behind service_control, a capability no application should hold.

That gap is real and is written up in docs/stdlib-design.md rather than papered over here. It needs one kernel change, reviewed on its own terms; this library is deliberately useful without it, and will not grow a userspace impersonation of it.

Where the unsafe lives

Nowhere in this crate. #![deny(unsafe_code)] below, with no exception - unlike a service, this is a library and exports no #[no_mangle] entry symbol, so it does not need even the one #[allow] that services carry.

Re-exports

pub use error::Error;

Modules

addr

Addresses. Pure parsing - no service, no SDK, and no formatter.

app

A program with the screen and the keyboard to itself while it runs: an app.

call

One way to ask a service for something, and get an honest answer.

cap

Capabilities: the rights a capability carries, and the operations on one.

driver

Device-neutral mechanisms for drivers (docs/driver-library.md). Not gated on the host test build: its pure arithmetic is unit-tested there, and the SDK-dependent half gates itself. gs::driver - the device-neutral mechanisms a driver is built from.

error

What can go wrong, and which of those you may safely try again.

file

A file as a capability, safely, from a service that serves other clients.

fs

Files, without the byte layout.

handover

A LIVE HANDOVER: a running service replaced by a new version without stopping - its state carried across, its name never unanswered.

io

Writing to the screen.

ipc

Messages between services: sending one, receiving one, and what the failures mean.

memory

A bounded block of this program’s own memory, for a working set too large for its stack.

net

The network, without the packing.

prelude

Everything a small program usually wants, in one use.

program

A program that does one job and ends: a utility.

record

Typed records: one table, and every rendering derived from it.

resource

Invoking a delegated resource capability, once, for everything that has one.

task

This service’s own execution: giving up the CPU, waiting, and what time it is.

trace

What this service is doing, and what every service has done: metrics, traces and the log tail.

Structs

ServiceContext

The service context, re-exported so an ordinary program never has to name godspeed_sdk.