proc

Process invocation and output capture: 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`	Receives values from a strand pipe.
`PipeSender`	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.
`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 = (: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

`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 a Unix-only field, so this is a Unix-only search
let mine = $
  for info = enumerate()
    if (info.unix_id.uid == uid)
      - $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`

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`

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.

`sub block … -> Str`

Captures the output of a block as a string.

Everything written is captured as a byte stream, without line decoding or normalization -- including values put into the strand's output, which contribute exactly their own bytes. For the console counterpart, which captures echo and print instead, use term.sub.

Parameters

Name	Type	Description
`block`	`(() -> Value)`	Block whose output to capture.
`:chomp?`	`Bool`	Remove one trailing LF or CRLF. True by default. This is a whole-capture strip, not a per-value one: it removes at most one line ending, from the end of the finished string.

Example

let output = sub do run echo hello
assert_eq $output "hello"

`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. Destructuring requires a trailing ... or **; symbol and string keys create proxies with the corresponding program names.

Example

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

let :git :cargo "clang++": clang ... = run