Module program 

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

A service runs until it is stopped. A utility is started by the shell for one command line, is handed its arguments, writes its output, and ends with a status - and the shell shows that output, pipes it onward, and reports the status. This module is the whole of what that needs:

use godspeed::{self as gs, ServiceContext};

#[allow(unsafe_code)]
#[no_mangle]
pub extern "C" fn service_main(ctx: ServiceContext) -> ! {
    let mut buf = [0u8; gs::program::ARGS_MAX];
    let args = gs::program::args(&ctx, &mut buf);
    let mut out = gs::program::Output::new(&ctx);
    let _ = core::fmt::Write::write_fmt(&mut out, format_args!("hello, {}\n", if args.is_empty() { "world" } else { args }));
    out.finish(0)
}

How it reaches the shell. The shell starts an installed utility through the supervisor wired to send to the shell (its first peer), sends the command line’s arguments as one message and then the end byte, and reads everything the program sends until the end byte - the same protocol every pipe stage speaks (docs/pipes.md), which is why a utility’s output can be piped like any built-in’s. Output::finish sends the end byte and then ends the program with its status (the Exit syscall, CLAUDE.md 14.5 amendment), so the shell can say whether it worked.

Structs

Output

What a program writes, sent to the shell a message at a time.

Constants

ARGS_MAX

The longest argument line a program is handed: one message.

ARGS_SECS

How long a program waits for its arguments before it takes the line as empty. The shell sends them as soon as the program has its endpoint, so this is only reached when nothing started it with any.

EOT

The end of a stream: the byte every pipe stage sends last.

Functions

args

The arguments this program was started with, as one line - or empty when it was given none.

exit

End this program now, with status. A program that writes output ends through Output::finish instead, so the shell receives the end of its output first.

mode

The mode this program was started in: a number its spawn request carried, 0 for every ordinary start. A program that does more than one thing - observe once or live, probe one test or another - reads which here. What a mode means is the program’s own.