Process#

Unix process creation and configuration.

Info

To use declarations from this page, include the <essence/process.hpp> header.

class process#

A Unix process abstraction.

Example

// calls the `ls` executable with `-alhF --color=auto` arguments
// and then returns with the program with the exit status of the process.
process p("ls", {"-alhF", "--color=auto"});
return p.spawn().wait().status();

std::string program#: The program name or full path to execute.

std::vector<std::string> arguments#: The arguments supplied to the process.

std::unordered_map<std::string, std::string> environment#

The process environment variables.

The default value when not supplied is to call env::map().

ioconfig io#: The input, output and error port configuration.

i32 status = 0#: After completion, the exit status of the process.

pid_t pid = -1#: When spawned, the process id.

std::string argzero#: The 0th argument in the exec argv, may be different from the program name.

process &spawn()#: Fork the parent process and execute the process in the child.

process &wait()#: Wait for the process to finish.

process &run()#: Shorthand to run spawn and wait, for the impatient.

output capture()#: Spawn the process, capture its’ output and error, then wait.

bool running()#: Check if the process is alive.

void kill(i32 sig = 15)#: Send a signal to the process, by default SIGTERM.

void exec()#: Execute the process without forking, replacing the current process. Marked with the [[noreturn]] attribute.

class pipeline#

Unix pipeline abstraction leveraging the process class.

Example

auto pl = process("echo", {"Hello there friend"})
        | process("grep", {"-v", "-i", "i"})
        | process("grep", {"-v", "-i", "t"});

pl.run(); // outputs: "Hello"

std::vector<process> processes#: The process members of the pipeline, in execution order.

std::vector<std::array<i32, 2>> pipes#: The pipe file descriptor pairs for each process.

pipeline &pipe(process p)#: Add a process to the pipeline.

pipeline &spawn()#: Spawn the pipeline.

pipeline &wait()#: Wait for the pipeline processes.

pipeline &run()#: Shorthand to spawn and wait for the pipeline.

i32 status() const#: Get the status of the last process in the pipeline.

std::vector<i32> statuses() const#: Get the statuses of all processes in the pipeline.

pipeline operator|(process lhs, process rhs)#: Construct a pipeline from two processes.

pipeline operator|(pipeline lhs, process rhs)#: Construct a pipeline from an existing pipeline and a process.

class output#

A container for process standard output and error.

std::string out#: The standard output.

std::string err#: The standard error.

output::output(std::string o, std::string e)#: Main constructor, accepting two strings.

output::output(std::pair<std::string, std::string> outerr)#: Alternative constructor, accepting a pair of strings.

class ioport#

Represents an IO stream as it relates to a process.

i32 fd = -1#: The file descriptor integer for the port.

ioport::ioport(i32 pfd)#: Main constructor, accepting a file descriptor integer.

ioport::ioport(const std::filesystem::path &path)#: Alternative constructor accepting a filesystem path.

static ioport::input()#: Static constructor using STDIN_FILENO.

static ioport::output()#: Static constructor using STDOUT_FILENO.

static ioport::error()#: Static constructor using STDERR_FILENO.

static ioport::null()#: Static constructor using /dev/null.

ioport &cloexec()#: Set the close-on-exec flag for the port.

bool is_open() const#: Check if the port is open.

void close()#: Close the port

operator bool() const#: Implicit conversion to bool.

class ioconfig#

Represents the three IO ports used by a process.

ioport in = ioport::input()#: The input port, defaulting to stdin.

ioport out = ioport::output()#: The output port, defaulting to stdout.

ioport err = ioport::error()#: The error port, defaulting to stderr.

explicit ioconfig::ioconfig()#: Constructor retaining default ports.

explicit ioconfig::ioconfig(ioport pIn, ioport pOut, ioport pErr)#: Constructor accepting all three port arguments.

explicit ioconfig::ioconfig(ioport pOutErr)#: Constructor accepting a single port for output and error, retaining default input.