process
Run child processes: spawn them, capture their output, stream their stdio, connect them into pipelines, deliver signals, manage process groups, and drive pseudo-terminals. Every command is an argv array of strings — there is no shell-string form anywhere, which structurally rules out command injection. Child stdio reuses the io handle model, and a child's environment is set per-call rather than globally.
process:run
[$process:run] -> element — Spawn an argv command, run it to completion, and return a proc-result with captured stdout, stderr, and exit code.
[?lib 'cx-stdlib/process']
[$process:run ("echo", "hello")]
cx-err:CXER0271
process:spawn
[$process:spawn] -> element — Start an argv command and return a proc handle for streaming its stdio and managing its lifecycle. Each of stdin/stdout/stderr is independently :pipe (default), :inherit, :discard, or a file path — a piped stream nobody drains fills at the OS pipe capacity and stops the child.
[?lib 'cx-stdlib/process']
[$process:spawn ("tail", "-f", "/var/log/app.log") stderr=:inherit]
cx-err:CXER0271
process:stdin
[$process:stdin] -> element — Return the child's writable stdin handle; closing it signals EOF to the child.
[?lib 'cx-stdlib/process']
[$process:stdin [$process:spawn ("cat")]]
cx-err:CXER0271
process:stdout
[$process:stdout] -> element — Return the child's readable stdout handle for incremental consumption.
[?lib 'cx-stdlib/process']
[$process:stdout [$process:spawn ("echo", "hi")]]
cx-err:CXER0271
process:stderr
[$process:stderr] -> element — Return the child's readable stderr handle for incremental consumption.
[?lib 'cx-stdlib/process']
[$process:stderr [$process:spawn ("echo", "hi")]]
cx-err:CXER0271
process:pid
[$process:pid] -> int — Return the child's operating-system process id.
[?lib 'cx-stdlib/process']
[$process:pid [$process:spawn ("sleep", "30")]]
cx-err:CXER0271
process:wait
[$process:wait] -> int — Block until the child exits, reap it, and return its exit code.
[?lib 'cx-stdlib/process']
[$process:wait [$process:spawn ("echo", "hi")]]
cx-err:CXER0271
process:wait-timeout
[$process:wait-timeout] -> [or int [sequence int]] — Block up to ms for the child to exit, returning its exit code or absence if still running.
[?lib 'cx-stdlib/process']
[$process:wait-timeout [$process:spawn ("sleep", "30")] 100]
cx-err:CXER0271
process:poll
[$process:poll] -> [or int [sequence int]] — Check without blocking, returning the child's exit code or absence if it is still running.
[?lib 'cx-stdlib/process']
[$process:poll [$process:spawn ("sleep", "30")]]
cx-err:CXER0271
process:usage
[$process:usage] -> [or map [sequence map]] — The finished child's resource use as {user-ns, sys-ns, peak-rss, wall-ns}: CPU time in user and kernel mode and wall time in nanoseconds, peak resident set in bytes, all from the reap; absence while the child still runs. A closed handle still answers.
[?lib 'cx-stdlib/process']
[$process:usage [$process:spawn ("echo", "hi")]]
cx-err:CXER0271
process:rss
[$process:rss] -> [or int [sequence int]] — A running child's resident set size now, in bytes, or absence once it has exited -- what a caller reads to stop a child past a memory cap.
[?lib 'cx-stdlib/process']
[$process:rss [$process:spawn ("sleep", "30")]]
cx-err:CXER0271
process:pid-alive
[$process:pid-alive] -> bool — Whether a process with this pid exists — any pid, not only one this program spawned (kill -0: a process owned by another user is alive).
[?lib 'cx-stdlib/process']
[$process:pid-alive 1]
cx-err:CXER0271
process:pid-command
[$process:pid-command] -> [or string [sequence string]] — The command line of a running process by pid, or absence when no such process runs.
[?lib 'cx-stdlib/process']
[$process:pid-command 1]
cx-err:CXER0271
process:limits
[$process:limits] -> map — This process's resource limits, each as {soft: n, hard: n} (:unlimited for none): nofile, core, cpu, data, fsize, stack, nproc, as -- those the platform has.
[?lib 'cx-stdlib/process']
[$process:limits]
cx-err:CXER0271
process:set-limit
[$process:set-limit] -> map — Set one of this process's limits (the soft value, and the hard one when given) and answer the {soft, hard} now in force; every child spawned after inherits it, as from ulimit. The OS refusing (a soft above the hard, a hard raised without privilege) raises CXER4010. For one child only, give run, spawn or pipeline a limits option instead.
[?lib 'cx-stdlib/process']
[$process:set-limit :nofile 4096]
cx-err:CXER0271
process:close
[$process:close] -> null — Release the handle, closing open stdio and reaping the child; idempotent and does not kill a running child.
[?lib 'cx-stdlib/process']
[$process:close [$process:spawn ("echo", "hi")]]
cx-err:CXER0271
process:pipeline
[$process:pipeline] -> element — Connect stages end-to-end and return a pipeline-result with a pipefail-aggregate exit code.
[?lib 'cx-stdlib/process']
[$process:pipeline ([stage [argv "printf" "a\nb\nERR\n"]], [stage [argv "grep" "ERR"]])]
cx-err:CXER0271
process:send-signal
[$process:send-signal] -> null — Deliver the named signal atom to the child; a no-op if it has already exited.
[?lib 'cx-stdlib/process']
[$process:send-signal [$process:spawn ("sleep", "30")] :hup]
cx-err:CXER0271
process:terminate
[$process:terminate] -> null — Deliver SIGTERM to the child for polite, catchable termination.
[?lib 'cx-stdlib/process']
[$process:terminate [$process:spawn ("sleep", "30")]]
cx-err:CXER0271
process:kill
[$process:kill] -> null — Deliver SIGKILL to the child for forced termination.
[?lib 'cx-stdlib/process']
[$process:kill [$process:spawn ("sleep", "30")]]
cx-err:CXER0271
process:kill-group
[$process:kill-group] -> null — Signal the child's whole process group, reaching it and every descendant as a unit.
[?lib 'cx-stdlib/process']
[$process:kill-group [$process:spawn ("./serve.sh") new-process-group=true] :term]
cx-err:CXER0271
process:spawn-pty
[$process:spawn-pty] -> element — Start a command attached to a fresh pseudo-terminal so it sees a real tty.
[?lib 'cx-stdlib/process']
[$process:spawn-pty ("vi", "notes.txt")]
cx-err:CXER0271
process:pty
[$process:pty] -> element — Return the pty master, one bidirectional io handle for the child's combined stdio.
[?lib 'cx-stdlib/process']
[$process:pty [$process:spawn-pty ("vi", "notes.txt")]]
cx-err:CXER0271
process:window-size
[$process:window-size] -> element — Return the pty's current window size as a size element with rows and cols.
[?lib 'cx-stdlib/process']
[$process:window-size [$process:spawn-pty ("vi", "notes.txt")]]
cx-err:CXER0271
process:set-window-size
[$process:set-window-size] -> null — Resize the pty's window and deliver SIGWINCH to the child.
[?lib 'cx-stdlib/process']
[$process:set-window-size [$process:spawn-pty ("vi", "notes.txt")] 40 120]
cx-err:CXER0271