DoxigAlpha
std › process › Child › run

run

Spawns a child process, waits for it, collecting stdout and stderr, and then returns. If it succeeds, the caller owns result.stdout and result.stderr memory.

Function parameters

Parameters

#
args:struct { allocator: mem.Allocator, argv: []const []const u8, cwd: ?[]const u8 = null, cwd_dir: ?fs.Dir = null, /// Required if unable to access the current env map (e.g. building a /// library on some platforms). env_map: ?*const EnvMap = null, max_output_bytes: usize = 50 * 1024, expand_arg0: Arg0Expand = .no_expand, progress_node: std.Progress.Node = std.Progress.Node.none, }

Type definitions in this namespace

Types

#
StdIo
Behavior of the child process's standard input, output, and error
WindowsExtension
File name extensions supported natively by `CreateProcess()` on Windows.

First argument in argv is the executable.

Functions

#
init
First argument in argv is the executable.
spawn
On success must call `kill` or `wait`.
kill
Forcibly terminates child process and then cleans up all resources.
waitForSpawn
On some targets, `spawn` may not report all spawn errors, such as `error.InvalidExe`.
wait
Blocks until child process terminates and then cleans up all resources.
collectOutput
Collect the output from the process's stdout and stderr.
run
Spawns a child process, waits for it, collecting stdout and stderr, and then returns.

Error sets in this namespace

Error Sets

#

Source

Implementation

#
pub fn run(args: struct {
    allocator: mem.Allocator,
    argv: []const []const u8,
    cwd: ?[]const u8 = null,
    cwd_dir: ?fs.Dir = null,
    /// Required if unable to access the current env map (e.g. building a
    /// library on some platforms).
    env_map: ?*const EnvMap = null,
    max_output_bytes: usize = 50 * 1024,
    expand_arg0: Arg0Expand = .no_expand,
    progress_node: std.Progress.Node = std.Progress.Node.none,
}) RunError!RunResult {
    var child = ChildProcess.init(args.argv, args.allocator);
    child.stdin_behavior = .Ignore;
    child.stdout_behavior = .Pipe;
    child.stderr_behavior = .Pipe;
    child.cwd = args.cwd;
    child.cwd_dir = args.cwd_dir;
    child.env_map = args.env_map;
    child.expand_arg0 = args.expand_arg0;
    child.progress_node = args.progress_node;

    var stdout: ArrayList(u8) = .empty;
    defer stdout.deinit(args.allocator);
    var stderr: ArrayList(u8) = .empty;
    defer stderr.deinit(args.allocator);

    try child.spawn();
    errdefer {
        _ = child.kill() catch {};
    }
    try child.collectOutput(args.allocator, &stdout, &stderr, args.max_output_bytes);

    return .{
        .stdout = try stdout.toOwnedSlice(args.allocator),
        .stderr = try stderr.toOwnedSlice(args.allocator),
        .term = try child.wait(),
    };
}