API Reference

class OS

Host OS surface: platform, architecture, host identity, directories, CPU count, and uptime. All queries are read-only snapshots.

Every method is static, so call them as OS.method() without constructing anything. Values come from the process that runs the program, which means they follow the environment (a TMPDIR override changes what tmpdir() reports) rather than a fixed build-time answer.

Result values are not errors: a query that cannot be answered returns a documented fallback (an empty string, "unknown", 0.0, or 1) instead of throwing. Check the value when it matters.

fn arch(): String

CPU architecture: "x86_64", "aarch64", or the Rust target-arch name.

This is the architecture of the running program, not of the physical machine. An x86_64 build under emulation reports "x86_64".

returns — architecture string, never empty.

import { OS } from "@std/os";

let is64 = OS.arch() == "x86_64" || OS.arch() == "aarch64";
print(is64);

Run in Playground

fn cpuCount(): Int

Logical CPU execution threads available to this process (at least 1).

This is the scheduler-visible count, so CPU affinity masks and container CPU quotas shrink it. A machine with 16 hardware threads limited to 4 cores reports 4. Returns 1 when the host cannot answer.

Use it to size worker pools.

returns — core count, never below 1.

import { OS } from "@std/os";

let workers = OS.cpuCount();
print(workers);

Run in Playground

fn eol(): String

End-of-line marker for this platform ("\r\n" on Windows, "\n" elsewhere).

Returns a string, not a character: its length is 2 on Windows and 1 everywhere else. Build multi-line output with it instead of hardcoding "\n", which leaves stray carriage returns when the same file is read on Windows.

returns — eol string.

import { OS } from "@std/os";

let header = "name" + OS.eol() + "value" + OS.eol();
print(header);

Run in Playground

fn homedir(): String

Current user's home directory (HOME/USERPROFILE, else "").

Returns "" when neither variable is set, which happens in stripped containers and in daemons started without a login environment. Treat the empty string as "unknown home" instead of a usable path.

returns — home directory path, or "" when undetermined.

import { OS } from "@std/os";

let home = OS.homedir();
if (home == "") {
print("no home directory in this environment");
}

Run in Playground

fn hostname(): String

System hostname ("unknown" when it cannot be determined).

Resolution order: the HOSTNAME variable, then the contents of /etc/hostname, then COMPUTERNAME on Windows. A container with none of those set reports "unknown" rather than an empty string.

returns — hostname string, never empty.

import { OS } from "@std/os";

print(OS.hostname() != "unknown");

Run in Playground

fn platform(): String

OS platform: "linux", "macos", "windows", or the Rust target-OS name.

FreeBSD, Solaris, and other targets keep their Rust names ("freebsd", "solaris"), so compare against the exact string rather than assuming one of the three common ones.

returns — platform string, never empty.

import { OS } from "@std/os";

if (OS.platform() == "windows") {
print("windows path separator rules");
}

Run in Playground

fn tmpdir(): String

System temporary directory (TMPDIR/TEMP/TMP, else the OS default).

The first non-empty variable wins, in that order, so TMPDIR set in the shell overrides the OS default. The directory is not created; it is whatever the host already reports, which is /tmp on Linux and macOS when none of the variables are set.

returns — temp directory path.

import { OS } from "@std/os";

print(OS.tmpdir());

Run in Playground

fn uptime(): Float

System uptime in fractional seconds (0.0 when unavailable).

Seconds since boot, not since the program started, and not per-core time. Currently reads /proc/uptime, so it returns 0.0 on macOS and Windows. Test uptime-gated logic against 0.0 as "unknown".

returns — uptime as Float.

import { OS } from "@std/os";

let seconds = OS.uptime();
if (seconds > 0.0) {
print("host has been up for a while");
}

Run in Playground