Layer 0 Spec — system Family

Technical specification — Version 1.0

Family overview

The air-sys-syscall::system module exposes miscellaneous system primitives: system information, machine identity, cryptographic entropy generation. It is the smallest family in layer 0, but it contains essential functions such as getrandom.

Family scope.

Four categories:

1. System information: uname, sysinfo.
2. Machine identity: gethostname, sethostname.
3. Cryptographic entropy: getrandom.
4. Privileged system actions: reboot (mentioned but not exposed).

Cross-cutting characteristics.

1. Heterogeneity. The functions have little in common semantically.
2. A few privileged operations. sethostname, reboot require CAP_SYS_ADMIN.
3. getrandom is the most important element. Cryptography, identifier generation.

Subsection 1: System information

uname

#![allow(unused)]
fn main() {
pub fn uname() -> Result<UtsName, Errno>;

#[derive(Debug, Clone)]
pub struct UtsName {
    pub sysname: CString,
    pub nodename: CString,
    pub release: CString,
    pub version: CString,
    pub machine: CString,
    pub domainname: CString,
}
}

Behavior.

Returns information about the system:

• sysname: OS name (“Linux”).
• nodename: machine name.
• release: kernel version (“5.15.0-91-generic”).
• version: kernel build information.
• machine: hardware architecture (“x86_64”, “aarch64”).
• domainname: NIS domain name (Linux-specific).

Performance. ~1-2 µs.

sysinfo

#![allow(unused)]
fn main() {
pub fn sysinfo() -> Result<SystemInfo, Errno>;

#[derive(Debug, Clone)]
pub struct SystemInfo {
    pub uptime: Duration,
    pub load_average: [f64; 3],  // 1, 5, 15 minutes
    pub total_ram: u64,
    pub free_ram: u64,
    pub shared_ram: u64,
    pub buffer_ram: u64,
    pub total_swap: u64,
    pub free_swap: u64,
    pub processes: u16,
    pub total_high: u64,
    pub free_high: u64,
    pub mem_unit: u32,
}
}

Behavior.

Returns global statistics about the system. Useful for monitoring tools.

Notes on the wrapper.

The kernel struct uses mem_unit. The Air wrapper performs the multiplication internally and exposes values in bytes directly.

The load_average values are converted to f64 by the wrapper.

Precision limits.

sysinfo is fast but imprecise. For detailed stats, read /proc/meminfo etc.

Performance. ~1-2 µs.

Subsection 2: Machine identity

gethostname and sethostname

#![allow(unused)]
fn main() {
pub fn gethostname() -> Result<CString, Errno>;
pub fn sethostname(name: &CStr) -> Result<(), Errno>;
}

Preconditions.

For sethostname: CAP_SYS_ADMIN required. name must have a length ≤ HOST_NAME_MAX (typically 64 bytes).

Behavior.

gethostname is implemented via uname() and extracts the nodename field.

sethostname changes the hostname. A privileged action, rarely used by applications.

Subsection 3: Cryptographic entropy

getrandom

#![allow(unused)]
fn main() {
pub fn getrandom(
    buf: &mut [u8],
    flags: GetrandomFlags,
) -> Result<usize, Errno>;

bitflags! {
    pub struct GetrandomFlags: u32 {
        const NONBLOCK = 1;
        const RANDOM = 2;
        const INSECURE = 4;
    }
}
}

Underlying syscall. getrandom (x86_64 #318, ARM64 #278). Available since Linux 3.17.

Behavior.

Fills the buffer with cryptographically secure random bytes. The modern and preferred mechanism for obtaining entropy on Linux.

Flag semantics.

• No flag (default): uses the urandom pool. Blocks if not yet initialized.
• NONBLOCK: returns EAGAIN instead of blocking.
• RANDOM: uses the random pool. Avoid except in special cases (cryptographically equivalent to urandom on modern Linux).
• INSECURE: returns immediately even if not initialized, but with reduced quality. Strictly reserved for non-cryptographic cases.

Air recommendation.

For 99% of uses: GetrandomFlags::empty().

Behavior with large buffers.

getrandom may return fewer bytes than requested for large buffers. Loop if necessary:

#![allow(unused)]
fn main() {
fn fill_random(buf: &mut [u8]) -> Result<(), Errno> {
    let mut offset = 0;
    while offset < buf.len() {
        let n = getrandom(&mut buf[offset..], GetrandomFlags::empty())?;
        offset += n;
    }
    Ok(())
}
}

Air may provide a getrandom_exact helper in layer 1.

Performance. ~1-2 µs for small buffers. For large ones, throughput is limited by the kernel CSPRNG.

Tests.

• Nominal test: fill a 32-byte buffer, verify that it is not all zeros.
• Variation test: two successive calls, verify that the buffers are different.
• Large buffer test: 4 KB with a loop.

Subsection 4: Privileged operations not exposed

reboot

reboot(2) allows rebooting or shutting down the machine. Not exposed in the public Air API. System lifecycle control is the responsibility of systemd.

Listed in UNSUPPORTED.md with justification.

system family summary

Exposed functions:

Total: 5 main public functions.

Non-wrapped syscalls (listed in UNSUPPORTED.md):

• reboot: system action reserved for init.
• syslog (reading the kernel ring buffer): marginal.
• setdomainname: legacy NIS, marginal.
• iopl, ioperm: direct I/O port access, privileged and rare.
• personality: changing process personality, out of scope for phase 0.

Types added to air-sys-types

• UtsName
• SystemInfo
• GetrandomFlags

That is 3 additional types.

Foundational decisions that emerged in the system family

1. gethostname implemented via uname.

Rather than a separate syscall. Saves one theoretical syscall.

2. getrandom is deliberately minimalist.

No sophisticated “generate N cryptographic bytes” helper in layer 0. Higher layers will provide those helpers.

3. INSECURE is exposed but discouraged.

The flag exists in the kernel; Air does not hide it. But the documentation insists that it is reserved for non-cryptographic cases.

4. reboot not exposed.

Not the role of a normal Air application.

Overall layer 0 assessment

With the system family, layer 0 is fully specified.

Summary by family.

Approximate total: ~213 public wrapper functions in layer 0.

air-sys-types crate: ~187 public types.

Document license: MPL 2.0 Status: Technical specification of the air-sys-syscall::system module (layer 0).