Skip to main content

Programs and the system

Command runs another program and waits for it, or starts it and goes on with a Process. ExitStatus says how a program ended, and ProcessError why it did not do its work. Environment reads the variables the program was started with, and Signals waits for the signals of the system. All of them are written in SG in the module std.

No shell reads the words of a Command: each argument reaches the program as it is written, so a text from outside never becomes a command of its own. The programs on this page start sh -c on Linux and macOS and cmd /c on Windows, since those are on every system, through a function shell that each of them holds whole.

Command​

SignatureWhat it does
Command(read string program)A program to run: a name looked for in the folders of PATH, or a path
void arg(ref this, read string word), void args(ref this, read string[] words)Arguments, after the ones before
void directory(ref this, read string path)The folder it works in
void setVariable(ref this, read string name, read string value)A variable of its environment, beside the ones of this program
void removeVariable(ref this, read string name), void clearVariables(ref this)One left out, or all of them
void input(ref this, read string text)What it reads as its input; without it, it reads nothing
Result<void, ProcessError> run(read this)Runs it and waits; an end with anything but 0 is Failed(status)
Result<string, ProcessError> output(read this)The same, and gives what it wrote, as text (InvalidText if it is not UTF-8)
Result<ExitStatus, IoError> status(read this)Runs it and gives how it ended, whatever that was
void pipeInput(ref this), pipeOutput, pipeErrorStreams to take from the Process that start gives
Result<Process, IoError> start(read this)Starts it and goes on
runAsync, outputAsync, statusAsyncThe same in an async function, with a read CancellationToken last; a cancel stops the program

A program run gets the output and the standard error of this one, with what was printed before already written out. A name is looked for only in the folders of PATH that are absolute, never in the folder the program works in.

Command shell(read string script) {
if OperatingSystem.isWindows() {
var cmd = Command("cmd")
cmd.arg("/c")
cmd.arg(script)
return cmd
}
var sh = Command("sh")
sh.arg("-c")
sh.arg(script)
return sh
}

Result<void, ProcessError> main() {
var hello = shell("echo hello")
var text = try hello.output()
print($"[{text.trim()}]")

match shell("exit 3").status() {
Ok(status) => print($"{status} {status.success()} {status == ExitStatus.Code(3)}")
Error(cause) => print(cause)
}
match shell("exit 4").run() {
Ok => print("ran")
Error(cause) => print(cause)
}
match Command("no-such-program-here").run() {
Ok => print("ran")
Error(Io(cause)) => print($"could not start: {cause}")
Error(Failed(status)) => print(status)
}
return Ok()
}

It prints:

[hello]
exited with code 3 false true
the program exited with code 4
could not start: NotFound

Process​

SignatureWhat it does
int id(read this)The number the system gave the program
StreamWriter? takeInput(ref this)Its input, once, after pipeInput
StreamReader? takeOutput(ref this), takeError(ref this)Its output, or its standard error, once
Result<ExitStatus, IoError> wait(this)Waits for it to end, and takes the Process
Result<ExitStatus, IoError> waitAsync(this, read CancellationToken token)The same, async
void kill(read this)Stops it at once (signal 9)
void terminate(read this)Asks it to stop (signal 15)
void signal(read this, Signal signal)Sends it a signal by its name

A Process kept in a local variable is waited for on every path. One that ends without that stops its program with the signal 9, so nothing goes on running unseen:

Result<void, IoError> main() {
var process = try Command("true").start()
print(process.id())
return Ok()
}
error: the program in `process` is not waited for at this `return`
a program that is not waited for is stopped where its `Process` ends, with the signal 9
Command shell(read string script) {
if OperatingSystem.isWindows() {
var cmd = Command("cmd")
cmd.arg("/c")
cmd.arg(script)
return cmd
}
var sh = Command("sh")
sh.arg("-c")
sh.arg(script)
return sh
}

Result<void, IoError> main() {
var command = shell("echo one&& echo two")
command.pipeOutput()
var process = try command.start()
var output = process.takeOutput() ?? panic("asked for with pipeOutput")
print(process.takeOutput() is null)
for line in output.lines() {
var text = try line
print($"<{text.trim()}>")
}
print(try process.wait())

var running = try shell("sleep 5").start()
running.kill()
print(try running.wait())
return Ok()
}

On Linux and macOS it prints:

true
<one>
<two>
exited with code 0
was stopped by signal 9

Windows has no signals to send: kill, terminate and signal end the program with the code 1 there, so the last line is exited with code 1.

ExitStatus and ProcessError​

ExitStatus is Code(int code), an end by itself (0 says the program did its work), or Signal(int number), a signal of the system that stopped it. bool success(read this) is true for Code(0). It prints as exited with code 3 or was stopped by signal 9; on Windows a code with its highest bit set is written in hex, as Windows writes it: exited with code 0xC0000005.

ProcessError is Io(IoError cause), the program could not be started (NotFound, PermissionDenied, InvalidInput for a word with a zero byte in it) or its output was not UTF-8, or Failed(ExitStatus status), it ran and did not end with 0. It prints as the IoError does, or the program exited with code 4.

Environment​

SignatureWhat it does
Result<string, VariableError> Environment.get(read string name)The text of the variable

VariableError is Missing, or InvalidText(long position) when what the variable holds is not UTF-8. The variables are only read: setting one while another thread reads one is not safe in C, and a program run by a Command gets an environment of its own through setVariable. Environment.set(...) is an error that says so. The words of the command line come to void main(List<string> args).

Signals​

While a listener of a signal lives, that signal does not end the program: it is kept until the program takes it, as in Go and Tokio, instead of a handler that would run between any two steps of any thread.

SignatureWhat it does
SignalListener Signals.listen(read Signal[] signals)Starts listening; no signal at all is a panic
Signal next(ref this)Waits for the next signal and gives it; one that came before is given at once
Result<Signal, Cancelled> nextAsync(ref this, read CancellationToken token)The same, async
void Signals.raise(Signal signal)Sends the signal to this program, as C's raise does

Signal is Interrupt (Ctrl-C), Terminate (the polite stop), Hangup, Quit, User1, User2 or WindowChange; their numbers are not given, since User1 is 30 on macOS and 10 on Linux. Several of one kind before a next are one, as the system does not count them either, and every listener of a signal gets it. On Windows Interrupt is Ctrl-C and Ctrl-Break, Terminate the console closed or the system shutting down; the others never come there, but raise hands them to listeners all the same.

void main() {
print(Environment.get("PATH") is Ok(_))
match Environment.get("SG_NO_SUCH_VARIABLE") {
Ok(value) => print(value)
Error(cause) => print(cause)
}
print(Environment.get("SG_NO_SUCH_VARIABLE") ?? "/")

var signals = Signals.listen(read List<Signal> { Signal.User1, Signal.Interrupt })
Signals.raise(Signal.User1)
Signals.raise(Signal.User1)
Signals.raise(Signal.Interrupt)
print(signals.next())
print(signals.next())
}

It prints:

true
Missing
/
User1
Interrupt

A server listens for Interrupt and Terminate, and when one comes, cancels a CancellationSource that its tasks look at (see Tasks), so that it ends its work instead of being cut off.