lib/process.x

Run commands and pipelines without a shell.

Primary API

Env

Env.get

String Env.get(String name)

Returns the value of this process’s environment variable name, or NULL when it is unset. The env option sets variables for a child instead.

Source: lib/process.x:548

Job

Job.check

Job Job.check(Job job)

Returns job once its status is zero, starting it and waiting as needed.

Raises: <cmd-fail> with command and status details, plus output and errors when they were captured, or the start causes of Job.start.

Source: lib/process.x:440

Job.cleanup

void Job.cleanup(Job job)

Terminates and reaps a job that is still running: SIGTERM, then SIGKILL to any stage still running a second later.

Source: lib/process.x:517

Job.equal

int Job.equal(Job, Job)

Provides the class default for Job.equal.

See Classes and system macros for the default behavior.

Source: lib/process.x:28

Job.errors

String Job.errors(Job job)

Returns the captured standard error of job, starting it and waiting as needed, or NULL when standard error was not captured or was empty.

Raises: the start causes of Job.start, or <bad-arg> when the captured text contains a NUL byte.

Source: lib/process.x:487

Job.free

void Job.free(Job)

Provides the class default for Job.free.

See Classes and system macros for the default behavior.

Source: lib/process.x:28

Job.hash

unsigned Job.hash(Job)

Provides the class default for Job.hash.

See Classes and system macros for the default behavior.

Source: lib/process.x:28

Job.kill

void Job.kill(Job job, int signal)

Sends signal to every stage of job that is still running.

Source: lib/process.x:509

Job.lines

List Job.lines(Job job)

Returns the captured standard output of job as lines without their endings.

Raises: the causes of Job.output.

Source: lib/process.x:480

Job.live

Job Job.live(Job job)

Makes job pass standard output through instead of capturing it, the same as options({stdout: <inherit>}), and returns it.

Raises: <bad-arg> for a job that has started.

Source: lib/process.x:399

Job.options

Job Job.options(Job job, Map options)

Sets options on job and returns it. The keys are atoms: dir names the working directory, env is a Map of variables added to the inherited environment, and input is a String given to the first stage’s standard input. stdout is capture, inherit, or a file path and applies to the last stage; stderr is inherit, capture, stdout to merge, or a file path and applies to every stage. A key set again replaces its earlier value.

#include "process.x"
int main(void) {
String root = %(pwd).job().options({dir: "/"}).output();
  return root == "/\n" ? 0 : 1;
}

Raises: <bad-arg> for an unknown key or a job that has started.

Source: lib/process.x:358

Job.output

String Job.output(Job job)

Returns the captured standard output of job, starting it and waiting as needed. A live job, or one whose output was empty, returns NULL.

Raises: the causes of Job.check, or <bad-arg> when the output contains a NUL byte.

Source: lib/process.x:471

Job.pipe

Job Job.pipe(Job job, List command)

Adds command after the last stage of job, reading that stage’s output, and returns the job. A pipeline command adds each of its stages.

Raises: <bad-arg> for a job that has started.

Source: lib/process.x:406

Job.ready

int Job.ready(Job job)

Reports whether every stage of job has exited, without blocking. A job that has not started reports 0.

Source: lib/process.x:495

Job.repr

String Job.repr(Job)

Provides the class default for Job.repr.

See Classes and system macros for the default behavior.

Source: lib/process.x:28

Job.run

void Job.run(Job job)

Passes standard output through, waits for job, and raises when its status is not zero: live() followed by check().

Raises: the causes of Job.live and Job.check.

Source: lib/process.x:462

Job.start

Job Job.start(Job job)

Starts job without waiting and returns it. A job that has started is returned unchanged.

Raises: <not-found> when a program or the dir option does not exist, <io-fail> when a pipe, fork, output file, or other start step fails, or <bad-arg> for an empty command.

Source: lib/process.x:418

Job.status

int Job.status(Job job)

Returns the status of job, starting it and waiting as needed: the exit status, or 128 plus a signal. A stage that never ran because the start raised reports 127. A status that is not zero is an ordinary result here.

Raises: the start causes of Job.start.

Source: lib/process.x:428

Job.str

String Job.str(Job)

Provides the class default for Job.str.

See Classes and system macros for the default behavior.

Source: lib/process.x:28

Job.var

Var Job.var(Job)

Provides the class default for Job.var.

See Classes and system macros for the default behavior.

Source: lib/process.x:28

Job.wait_any

Job Job.wait_any(Array jobs)

Removes and returns the first job in jobs that has finished, waiting until one does. An empty jobs returns NULL.

Raises: <bad-arg> when a job in jobs has not started.

Source: lib/process.x:529

Job.write_repr

Buffer Job.write_repr(Job, Buffer)

Provides the class default for Job.write_repr.

See Classes and system macros for the default behavior.

Source: lib/process.x:28

Job.write_str

Buffer Job.write_str(Job, Buffer)

Provides the class default for Job.write_str.

See Classes and system macros for the default behavior.

Source: lib/process.x:28

List

List.job

Job List.job(List command)

Returns a Job for command, a command or pipeline, without starting it. The job captures standard output and passes standard error through. Its first result starts it, waits, and records the run. A Job destination calls this converter, so the call is usually left implicit.

#include "process.x"
int main(void) {
Job job = %(printf "a\nb\n");
  return job.status() == 0 && job.lines().len() == 2 ? 0 : 1;
}

Source: lib/process.x:338

Var

Var.job

Job Var.job(Var)

Provides the class default for Var.job.

See Classes and system macros for the default behavior.

Source: lib/process.x:28

Public types

Env

typedef enum Env { ENV_NAMESPACE } Env

The receiverless owner of Env.get.

Source: lib/process.x:41

Job

class Job struct { List stages; struct _Launch *launch; long *pids; int *statuses; int count, started, finished, status, nul_output, nul_errors; File output_file, errors_file; String output_text, errors_text; } *

A command or pipeline and the record of its one run. A $auto job that is still running when its block exits is terminated and reaped.

Source: lib/process.x:28

Design notes

A command is an ordinary List. Each element’s str becomes one argument and no shell reads the words, so %(grep $pattern $file) passes a pattern containing spaces or quotes as a single argument. A List whose first element is itself a List is a pipeline, one command per element. List.job turns a command into a Job, which holds its stages and stream options until the first result requested starts it. That run is recorded, so a job runs exactly once however many results are read from it.

A pipeline’s status is the status of its last failing stage, or zero when every stage succeeds. A signalled stage reports 128 plus the signal.

This module also owns the calling process’s own environment, which a script reads to decide what to run.

Tests and examples

make verify (unittest/test-process.x) and make examples (scripts/line-counts).