nish:process
The process and its host: exit, the environment, children, signals, the clocks, scheduling, and the size of the machine.
import {
arch,
argv,
availableParallelism,
exit,
getenv,
kill,
monotonicNanos,
platform,
readSignal,
setCpuAffinity,
setIdlePriority,
setNice,
signalFd,
spawn,
spawnPiped,
spawnPipedWithin,
spawnSync,
spawnSyncTo,
spawnWithFds,
totalMemory,
waitPid,
wallClockNanos,
} from "nish:process";
import { spawn, waitPid, kill, availableParallelism } from "nish:process";
const pid = spawn(["sleep", "5"]);
if (pid > 0) {
kill(pid, 15);
const done = waitPid(pid, 0);
}
const workers = availableParallelism();
availableParallelism
How many CPUs the program may use: the smallest of the CPUs online, the ones its thread may run on (an affinity mask, a container's cpuset), a cgroup v2 CPU quota rounded up, and NISH_NUM_THREADS when that is a positive number, which can lower the count and never raise it.
exit
The global process.exit: a terminator, which never is how tsc spells it.
getenv
The value of environment variable name as the call runs.
kill
Send sig to pid.
monotonicNanos
CLOCK_MONOTONIC in nanoseconds.
readSignal
Block until SIGTERM or SIGINT arrives.
setCpuAffinity
Pin the calling process to the one CPU cpu with sched_setaffinity.
setIdlePriority
Move this process to SCHED_IDLE, which runs it only when nothing else wants the CPU.
setNice
Set the nice value with setpriority(PRIO_PROCESS, 0, n).
signalFd
A descriptor that becomes readable when SIGTERM or SIGINT arrives: the read end of a pipe a sigaction handler writes one byte to per signal, so the signals' default action never runs, whichever thread a signal lands on.
spawn
Start argv[0], searched on PATH, exactly as spawnSync does (the same vector, environment, streams and working directory), without waiting.
spawnPiped
The same run as spawnSync, with every stream a pipe: the child reads stdin's bytes and then end of file, and whatever it writes to its stdout and stderr is appended to stdout and stderr, which keep what they held.
spawnPipedWithin
spawnPiped with a deadline: the same captured run, killed with SIGKILL and reaped once timeoutMs milliseconds have passed since it started, and a negative timeoutMs is no deadline, so -1 makes it spawnPiped.
spawnSync
Run argv[0], searched on PATH, with argv as its argument vector, and wait for it.
spawnSyncTo
The same run as spawnSync, with each stream sent to a file rather than inherited.
spawnWithFds
spawn, with the child holding fds[i] as descriptor 3 + i, close-on-exec cleared there.
totalMemory
The machine's physical memory: _SC_PHYS_PAGES times the page size on Linux, hw.memsize on Darwin.
waitPid
Reap a child.
wallClockNanos
CLOCK_REALTIME in nanoseconds since 1970-01-01 UTC: Date.now's clock at a nanosecond's grain.
Each export is the global of the same name, renamed: the compiler emits the
same IR for either spelling. A call that can fail answers a value, a
negative errno or -1 or null, rather than exiting, because the language
has no exceptions and a caller has to be able to turn the failure into its
own diagnostic.
A wasm32 target has no processes and no host to ask, so the checker
refuses spawn, spawnWithFds, kill, waitPid, availableParallelism,
totalMemory, the scheduling calls, signalFd and readSignal there;
a WASI build answers -1 from spawnSync,
spawnSyncTo and spawnPiped. spawn, kill, waitPid and the scheduling
calls write state outside the program, so a scope's task or a parallel body
that calls one is refused as any shared write is.
A supervisor polls
A blocking waitPid(pid, 0) cannot be woken by
SIGTERM once signalFd() is installed, so a supervisor that must answer a
signal while its children run reaps with flag 1 (WNOHANG) on each tick of a
pollWait loop that also watches the signal descriptor, and stops its
children with kill when readSignal answers.
The rules: https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#directories-and-subprocesses, https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#the-environment, https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#the-clock, https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#the-host-the-wall-clock-entropy-file-times-and-signals, https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#children-and-the-machine-spawn-kill-waitpid-availableparallelism-totalmemory and https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#scheduling-setnice-setidlepriority-setcpuaffinity
Functions
availableParallelism
How many CPUs the program may use: the smallest of the CPUs online, the
ones its thread may run on (an affinity mask, a container's cpuset), a
cgroup v2 CPU quota rounded up, and NISH_NUM_THREADS when that is a
positive number, which can lower the count and never raise it. It needs no
--threads, and a task may call it.
const availableParallelism: () => i32
returnsi32The count, at least 1.
exit
The global process.exit: a terminator, which never is how tsc
spells it.
const exit: (code: i32) => never
codei32requiredThe exit status.
returnsneverNever: the program ends.
getenv
The value of environment variable name as the call runs. The bytes are
copied into the arena, so the result is an ordinary string that outlives
any later change to the environment, and it is bytes: a value that is not
valid UTF-8 comes back as those bytes. Two reads are two calls, never
folded into one, because linked C may change the environment between
them. There is no setenv.
const getenv: (name: string) => string | null
namestringrequiredThe variable's name.
returnsstring | null
The value, a zero-length string for a variable set to nothing
(CC=), or null when the variable is unset; narrow it with
if (cc !== null).
kill
Send sig to pid. Only 0, 2 (SIGINT), 9 (SIGKILL) and 15 (SIGTERM) are
taken, whose numbers are the same on Linux and Darwin, so a number means
the same signal on every host. A positive pid may be any process of this
user, not only a child.
const kill: (pid: i32, sig: i32) => i32
pidi32requiredThe process, above 0.
sigi32required0, 2, 9 or 15.
returnsi32
0, or a negative errno: -22 for any other sig or a pid of
0 or below (which kill(2) reads as a process group or every
process), -3 ESRCH when no process has the pid (a child already reaped
included), -1 EPERM when it is another user's.
monotonicNanos
CLOCK_MONOTONIC in nanoseconds. The origin is arbitrary, so only the
difference between two reads means anything: it is not comparable between
two processes or two machines, and it is not a date. Two reads with work
between them never fold into one.
const monotonicNanos: () => i64
returnsi64The clock's reading.
readSignal
Block until SIGTERM or SIGINT arrives. It can wait forever.
const readSignal: (fd: i32) => i32
fdi32required
The descriptor signalFd() answered; an i32 in both number
modes, and an f64, i64 or string is refused rather than converted.
returnsi32
15 or 2, or -1 for a descriptor that is not signalFd()'s and
for a read that fails.
setCpuAffinity
Pin the calling process to the one CPU cpu with sched_setaffinity.
Narrow-only: it never moves a process onto a CPU it was kept off.
availableParallelism() answers 1 afterwards, and children started
afterwards inherit the mask.
const setCpuAffinity: (cpu: i32) => i32
cpui32requiredThe CPU's index.
returnsi32
0; -22 with no change for a cpu below 0, at or past
CPU_SETSIZE, or outside the CPUs the process may already run on; -95
on Darwin and under Node, which have no affinity call.
setIdlePriority
Move this process to SCHED_IDLE, which runs it only when nothing else
wants the CPU. An unprivileged process can never leave it, and an idle
process can starve on a saturated machine, so a caller keeps a
normal-priority fallback (setNice(19), or a deadline) for work that must
finish. Per thread, as setNice is.
const setIdlePriority: () => i32
returnsi32
0, a negative errno, or -95 on Darwin, which has no such
policy.
setNice
Set the nice value with setpriority(PRIO_PROCESS, 0, n). Lower-only, even
as root: the priority never rises. It sets the calling thread's value and
every thread's started after it, so it belongs at the top of main;
children started afterwards inherit it.
const setNice: (n: i32) => i32
ni32requiredThe nice value, 0..19.
returnsi32
0, or a negative errno: -22 EINVAL outside 0..19 and -13
EACCES below the current value, both with no system call.
signalFd
A descriptor that becomes readable when SIGTERM or SIGINT arrives: the
read end of a pipe a sigaction handler writes one byte to per signal, so
the signals' default action never runs, whichever thread a signal lands
on. Installing the handler overrides a disposition the process started
with, so a signal its parent ignored is heard. Made once.
const signalFd: () => i32
returnsi32The same descriptor every call, or -1 when it cannot be made.
spawn
Start argv[0], searched on PATH, exactly as spawnSync does (the same
vector, environment, streams and working directory), without waiting. The
child is this process's until waitPid reaps it; one never reaped stays a
zombie until the program exits, as in C. Test pid > 0 before handing the
answer on: a failure such as -1 passed to waitPid reads as "any child".
const spawn: (argv: string[]) => i32
argvstring[]requiredThe program and its arguments.
returnsi32
The child's pid, or a negative errno: -22 EINVAL for an empty
vector or an argument holding a NUL, posix_spawnp's own error
otherwise, so a program that is not there is -2 ENOENT. Under --sandbox with a list of granted
programs, a spawn that cannot be held to one program is refused: -11
(EAGAIN), -38 (ENOSYS), -10 (ECHILD) or the kernel's own error, with a line
on stderr.
spawnPiped
The same run as spawnSync, with every stream a pipe: the child reads
stdin's bytes and then end of file, and whatever it writes to its stdout
and stderr is appended to stdout and stderr, which keep what they held.
It is the run for a child that takes a secret on stdin, which ps and
/proc do not show. A child that exits without reading its stdin is not a
failure.
The child inherits the environment and working directory, and no descriptor
of the program but its three streams; it starts with SIGPIPE as the program
had it, and the program's own SIGPIPE from writing to a child that stopped
reading is absorbed. One poll loop writes and drains, so a child that
fills one pipe cannot deadlock the parent.
const spawnPiped: (
argv: string[],
stdin: readonly u8[],
stdout: u8[],
stderr: u8[],
) => i32
argvstring[]requiredThe program and its arguments.
stdinreadonly u8[]requiredThe bytes the child reads.
stdoutu8[]required
Grows by the child's stdout; neither readonly nor a typed
array, since the runtime pushes onto it.
stderru8[]requiredGrows by the child's stderr, under the same rule.
returnsi32
The status or 128 + n as spawnSync answers; -1 for an empty
vector, a child that cannot be started, a pipe or poll that fails, and
a WASI build; -2 when a stream passes 16 MiB (NISH_PIPED_CAP), which
kills the child with SIGKILL and leaves that array holding the first
16 MiB.
spawnPipedWithin
spawnPiped with a deadline: the same captured run, killed with SIGKILL
and reaped once timeoutMs milliseconds have passed since it started, and
a negative timeoutMs is no deadline, so -1 makes it spawnPiped. The
deadline covers the whole run, the wait for the child's exit included, on
the monotonic clock. Only the child's pid is killed, never a grandchild,
and a grandchild that keeps an output pipe open makes the run wait for it
until the deadline.
const spawnPipedWithin: (
argv: string[],
stdin: readonly u8[],
stdout: u8[],
stderr: u8[],
timeoutMs: i32,
) => i32
argvstring[]requiredThe program and its arguments.
stdinreadonly u8[]requiredThe bytes the child reads.
stdoutu8[]required
Grows by the child's stdout, the bytes read before a kill
included; neither readonly nor a typed array.
stderru8[]requiredGrows by the child's stderr, under the same rule.
timeoutMsi32requiredThe milliseconds the run may take; negative for none.
returnsi32
spawnPiped's answer (the status or 128 + n, -1, or -2 for
a stream past 16 MiB), or -3 when the deadline passed and the child was
killed.
spawnSync
Run argv[0], searched on PATH, with argv as its argument vector, and
wait for it. The child inherits this process's environment, streams and
working directory. The runtime keeps each element's bytes pointer for the
child, so the array escapes; an embedded NUL truncates an argument.
const spawnSync: (argv: string[]) => number
argvstring[]requiredThe program and its arguments.
returnsnumber
The child's exit status, 128 + n when signal n killed it, or
-1 when the vector is empty, when the child cannot be started or waited
for, and always on WASI.
spawnSyncTo
The same run as spawnSync, with each stream sent to a file rather than
inherited. Each path is created or truncated at 0644, as writeFileSync
does, and an empty path leaves that stream inherited, so one call can
capture stdout and let stderr through. The two paths must not name one
file: each is opened separately, with its own offset, so the streams
would overwrite rather than interleave.
const spawnSyncTo: (
argv: string[],
stdoutPath: string,
stderrPath: string,
) => number
argvstring[]requiredThe program and its arguments.
stdoutPathstringrequiredThe file for the child's stdout, or "" to inherit it.
stderrPathstringrequiredThe file for the child's stderr, or "" to inherit it.
returnsnumber
Every answer spawnSync gives, and -1 when a symbolic link is
the last component of either path.
spawnWithFds
spawn, with the child holding fds[i] as descriptor 3 + i,
close-on-exec cleared there. Its streams 0 to 2 are this process's, and no
other descriptor of this process reaches it but one opened without
close-on-exec, which nothing the runtime opens is. Any order works: fds
may list a descriptor that is already its own target ([3]), another
entry's target ([4, 3]), or the same one twice. The child shares each
descriptor's open file, its offset and its status flags, O_NONBLOCK
among them, and this process keeps its own. Reap the pid with waitPid.
const spawnWithFds: (
argv: string[],
fds: readonly i32[],
) => i32
argvstring[]requiredThe program and its arguments.
fdsreadonly i32[]required
The descriptors the child receives from 3 onward; an empty
array is spawn exactly.
returnsi32
The child's pid, or a negative errno: -22 for more than 64
descriptors or a negative one (before anything is opened or started),
-9 for one that is not open, -24 (or -22 above the descriptor
limit) for a scratch descriptor the system cannot give, and spawn's
errors.
totalMemory
The machine's physical memory: _SC_PHYS_PAGES times the page size on
Linux, hw.memsize on Darwin. The machine's, not a cgroup's limit. A task
may call it.
const totalMemory: () => i64
returnsi64The bytes, or -1 where the host does not say.
waitPid
Reap a child. The status is spawnSync's: the exit code, or 128 + n
when signal n ended it. An array because the language has no tuple.
const waitPid: (pid: i32, flags: i32) => i32[]
pidi32requiredA child's pid, or -1 for any child.
flagsi32required0 to block, or 1 for WNOHANG.
returnsi32[]
A fresh [pid, status]; [0, 0] for a WNOHANG wait with a child
left and none exited; [-10, 0] ECHILD with no child to wait for,
[-4, 0] EINTR when a signal interrupted the wait (after signalFd() a
blocking wait restarts and never sees it), [-22, 0] for any other flag
bit or a pid that is neither -1 nor positive.
wallClockNanos
CLOCK_REALTIME in nanoseconds since 1970-01-01 UTC: Date.now's clock
at a nanosecond's grain. It steps, and can go backwards, when the system
time is set, so a duration is monotonicNanos's job. Not refused on wasm.
const wallClockNanos: () => i64
returnsi64The timestamp.
Constants
arch
arch: string
The architecture: "x64", "arm64", or "unknown".
argv
argv: readonly string[]
The command line; argv[0] is the program path, as in C. Read-only.
platform
platform: string
The operating system the program runs on: "linux", "darwin", or "unknown".

