proc

Process invocation: running external programs, and inspecting or controlling processes that are not children of this one.

See External Programs for lookup, redirection, capture and pipeline behavior.

Types

Type	Description
Error	Raised when an external program exits unsuccessfully.
Info	Information about a process at a moment in time.
PipeReceiver[T]	Receives values from a strand pipe.
PipeSender[T]	Sends values to a strand pipe.
Proc	An open handle to a process that is not a child of this one.
Program	Function proxy for an external program.
@Run	The type of run.
Status	How a process that is not a child of this one exited.
Signal	A signal name, with or without a SIG prefix, such as :TERM: or :SIGTERM:.

Signal

@let Signal = $
  | :HUP:
  | :INT:
  | :QUIT:
  | :ILL:
  | :TRAP:
  | :ABRT:
  | :IOT:
  | :EMT:
  | :FPE:
  | :KILL:
  | :BUS:
  | :SEGV:
  | :SYS:
  | :UNUSED:
  | :PIPE:
  | :ALRM:
  | :TERM:
  | :URG:
  | :STOP:
  | :TSTP:
  | :CONT:
  | :CHLD:
  | :CLD:
  | :TTIN:
  | :TTOU:
  | :IO:
  | :POLL:
  | :XCPU:
  | :XFSZ:
  | :VTALRM:
  | :PROF:
  | :WINCH:
  | :INFO:
  | :USR1:
  | :USR2:
  | :STKFLT:
  | :PWR:
  | :THR:
  | :LIBRT:
  | :SIGHUP:
  | :SIGINT:
  | :SIGQUIT:
  | :SIGILL:
  | :SIGTRAP:
  | :SIGABRT:
  | :SIGIOT:
  | :SIGEMT:
  | :SIGFPE:
  | :SIGKILL:
  | :SIGBUS:
  | :SIGSEGV:
  | :SIGSYS:
  | :SIGUNUSED:
  | :SIGPIPE:
  | :SIGALRM:
  | :SIGTERM:
  | :SIGURG:
  | :SIGSTOP:
  | :SIGTSTP:
  | :SIGCONT:
  | :SIGCHLD:
  | :SIGCLD:
  | :SIGTTIN:
  | :SIGTTOU:
  | :SIGIO:
  | :SIGPOLL:
  | :SIGXCPU:
  | :SIGXFSZ:
  | :SIGVTALRM:
  | :SIGPROF:
  | :SIGWINCH:
  | :SIGINFO:
  | :SIGUSR1:
  | :SIGUSR2:
  | :SIGSTKFLT:
  | :SIGPWR:
  | :SIGTHR:
  | :SIGLIBRT:

A signal name, with or without a SIG prefix, such as :TERM: or :SIGTERM:.

Functions

console[R] block -> R

Runs a block for its effect on the console: its input is std.null and its output is term.default.

Programs run inside it read nothing and write to the console, whatever the caller's input and output are, so a caller that only runs programs for their effect needs no channels of its own.

Parameters

Name	Type	Description
block	((<Iter[Never], >Sink[Value]) -> R)	Block to run.

Example

console do
  run make
  run make install

enumerate() -> Iter[Info]

Lists the processes running on the target.

Returns

An iterator of process information. It cannot be destructured.

Example

for info = enumerate()
  echo "$(info.pid) $(info.name)"

# `unix_id` is `nil` on non-Unix targets
let root_owned = $
  for info = enumerate()
    if (info.unix_id && info.unix_id.uid == 0)
      - $info

info … -> Info

Describes the process that currently owns pid, or the target process itself when pid is omitted.

Because this bypasses open, it works on protected processes on Windows that would otherwise fail with a permission error.

Parameters

Name	Type	Description
pid?	Int	Process ID. Defaults to the target process: the one serving the current VFS, which is the process running this interpreter when none is connected, and otherwise the agent at the far end of the connection. Pair it with shell.with_host to reach this interpreter while a target is selected.

Errors

Exception	Condition
sys.NotFoundError	No such process

Example

let info = info $pid
echo "$(info.name) started as $(info.cmdline)"

# The PID of this interpreter, whatever target is selected
let mine = shell.with_host do info()
echo $mine.pid

open target -> Proc ^{overload 1 of 2}

Opens a handle to a process.

Parameters

Name	Type	Description
target	(Info | Int)	Information record, or a raw PID.

Errors

Exception	Condition
sys.NotFoundError	No such process, or the PID was recycled
sys.PermissionDeniedError	The caller may not open the process

Example

let p = open $pid
try
  echo $p.info().name
finally
  p.close()

open[R] target block -> R ^{overload 2 of 2}

Opens a handle to a process and runs a block with it. The handle is closed when the block returns.

let name = open $pid do |p|
  p.info().name

Parameters

Name	Type	Description
target	(Info | Int)	Information record, or a raw PID.
block	((Proc) -> R)	Block to run with the handle.

with_policy[R] block … -> R

Runs a block with temporary process termination defaults.

The signal setting is retained when the strand later targets a Unix VFS. Windows launches always use CTRL_BREAK_EVENT. With force: false, a process that outlives the grace period is orphaned.

Parameters

Name	Type	Description
block	(() -> R)	Block to run.
:signal?	Signal	Unix signal. :TERM: by default.
:grace?	(time.Duration | Int | Float)	Time before forced termination. Five seconds by default.
:force?	Bool	Force termination after the grace period.

Example

with_policy signal: :INT: grace: 2.5 do
  run worker

Values

run

Runs an external program, or creates a Program proxy.

Calling it takes the program name or path as its first argument, followed by the launch arguments accepted by Program. Index it with a Str or fs.Path to create a proxy.

Example

run git status
run["clang++"] --version

let git = run["git"]
git status