std.os

The program and the operating system it runs on: the arguments (args), the environment (env, envs, setEnv), the working directory (cwd, setCwd), ending the program (exit), facts about the machine (platform, arch, hostname, cpuCount, pid, homeDir, tempDir), and the system's signals (Signal, signals). A signal's watcher is a thread of its own, whose one task hands each caught signal on.

Examples

import std.io { println };
import std.os;

println(os.env("LYRIC_EXAMPLE_UNSET") ?? "not set");
println(os.cpuCount() > 0);

not set
true

Types

Signal enum — A signal of the system, by an abstract name: Windows knows only Interrupt (Ctrl+C, Ctrl+Break) and Terminate (its console closes).

Functions

pub fn args(): string[]

Returns the program's arguments, its own name first; a new array each call. On Windows they are read from the command line as UTF-16, so a name that is not ASCII comes as it was typed.

pub fn env(name: StringView): ?string

Returns the value of the environment variable name, or null where it is not set.

pub fn envs(): Map<string, string>

Returns a snapshot of the whole environment, mapping names to values.

pub fn setEnv(name: StringView, value: StringView): void

Sets the environment variable name to value, for this process and the processes it starts. Another thread reading the environment through C at the same time is a race the system does not guard against: set variables before the threads start.

Panics

Panics when name is empty or holds = or a NUL, when value holds a NUL, and when the system refuses the change.

pub fn cwd(): string throws IoError

Returns the working directory.

Errors

Throws IoError when the system cannot report it.

pub fn setCwd(path: StringView): void throws IoError

Makes path the working directory.

Errors

Throws IoError when the system refuses, for example for a path that does not exist.

pub fn exit(code: int): never

Ends the program at once with exit code code: what the console holds is written, but no defer or using runs and no other task is waited for.

pub fn platform(): Platform

Returns the system the program runs on.

pub fn arch(): Arch

Returns the machine architecture the program runs on.

pub fn homeDir(): ?string

Returns the user's home directory — HOME, on Windows USERPROFILE —, or null where it is not set or empty.

pub fn tempDir(): string

Returns the system's directory for temporary files: TMPDIR where it is set and not empty, else /tmp; on Windows the one GetTempPathW reports. fs.tempDir() makes a new directory in it.

Panics

Panics when the runtime cannot report the directory.

pub fn hostname(): string throws IoError

Returns the machine's name.

Errors

Throws IoError when the system cannot report it.

pub fn cpuCount(): int

Returns the number of processors online for the program, at least one.

pub fn pid(): int

Returns the process's id.

pub fn signals(wanted: Signal...): Channel<Signal>

Returns a channel the given signals arrive on: from now on they no longer do what the system does with them — mostly end the program — but arrive here. Each comes to every channel that asked for it. Signals are not counted: two that come before the first was delivered may arrive as one, and one that finds the channel's buffer of sixteen full is lost for that channel. Closing the channel ends the subscription at once: a signal no channel asks for any more gets the system's handling again from then on. KILL, STOP and the faults never arrive.