Skip to main content

ChildProcess (interface)​

A class which represents a child process. The process may or may not be running.

This class is the API used internally by the exec function to spawn child processes.

Generally, you should not need to use the ChildProcess class directly, and should use exec or $ instead. However, you may need to use it in some special cases, like when specifying custom stdio for a process, or spawning a non-blocking long-running process.

declare interface ChildProcess {
  args: Array<string>;
  cwd: Path;
  env: {
    [key: string]: string;
  };
  stdio: {
    in: FILE;
    out: FILE;
    err: FILE;
  };
  get state(): ChildProcessState;
  get pid(): number | null;
  start(): number;
  waitUntilComplete():
    | {
        status: number;
        signal: undefined;
      }
    | {
        status: undefined;
        signal: number;
      };
}

ChildProcess.args (property)​

The argv for the process. The first entry in this array is the program to run.

args: Array<string>;

ChildProcess.cwd (Path property)​

The current working directory for the process.

cwd: Path;

ChildProcess.env (object property)​

The environment variables for the process.

env: {
  [key: string]: string;
};

ChildProcess.stdio (object property)​

The standard I/O streams for the process. Generally these are the same as std.in, std.out, and std.err, but they can be customized to write output elsewhere.

stdio: {
  in: FILE;
  out: FILE;
  err: FILE;
};

ChildProcess.stdio.in (FILE property)​

Where the process reads stdin from

in: FILE;

ChildProcess.stdio.out (FILE property)​

Where the process writes stdout to

out: FILE;

ChildProcess.stdio.err (FILE property)​

Where the process writes stderr to

err: FILE;

ChildProcess.state (getter)​

get state(): ChildProcessState;

ChildProcess.pid (getter)​

get pid(): number | null;

ChildProcess.start (method)​

Spawns the process and returns its pid (process id).

start(): number;

ChildProcess.waitUntilComplete (method)​

Blocks the calling thread until the process exits or is killed.

waitUntilComplete(): {
  status: number;
  signal: undefined;
} | {
  status: undefined;
  signal: number;
};

ChildProcessState (type)​

declare type ChildProcessState =
  | {
      id: "UNSTARTED";
    }
  | {
      id: "STARTED";
      pid: number;
    }
  | {
      id: "STOPPED";
      pid: number;
    }
  | {
      id: "CONTINUED";
      pid: number;
    }
  | {
      id: "EXITED";
      oldPid: number;
      status: number;
    }
  | {
      id: "SIGNALED";
      oldPid: number;
      signal: number;
    };

ChildProcessOptions (type)​

Options to be passed to the ChildProcess constructor. Their purposes and types match the same-named properties found on the resulting ChildProcess.

declare type ChildProcessOptions = {
  cwd?: string | Path;
  env?: {
    [key: string]: string;
  };
  stdio?: {
    in?: FILE;
    out?: FILE;
    err?: FILE;
  };
  logging?: {
    trace?: (...args: Array<any>) => void;
  };
};

ChildProcessOptions.cwd (property)​

The current working directory for the process.

cwd?: string | Path;

ChildProcessOptions.env (object property)​

The environment variables for the process.

env?: {
  [key: string]: string;
};

ChildProcessOptions.stdio (object property)​

The standard I/O streams for the process. Generally these are the same as std.in, std.out, and std.err, but they can be customized to write output elsewhere.

stdio?: {
  in?: FILE;
  out?: FILE;
  err?: FILE;
};

ChildProcessOptions.stdio.in (FILE property)​

Where the process reads stdin from

in?: FILE;

ChildProcessOptions.stdio.out (FILE property)​

Where the process writes stdout to

out?: FILE;

ChildProcessOptions.stdio.err (FILE property)​

Where the process writes stderr to

err?: FILE;

ChildProcessOptions.logging (object property)​

Options which control logging

logging?: {
  trace?: (...args: Array<any>) => void;
};

ChildProcessOptions.logging.trace (function property)​

Optional trace function which, if present, will be called at various times to provide information about the lifecycle of the process.

Defaults to the current value of logger.trace. logger.trace defaults to a function which writes to stderr.

trace?: (...args: Array<any>) => void;

ChildProcessConstructor (interface)​

declare interface ChildProcessConstructor {
  new (
    args: string | Path | Array<string | number | Path>,
    options?: ChildProcessOptions,
  ): ChildProcess;
  readonly prototype: ChildProcess;
}

ChildProcessConstructor new(...) (construct signature)​

Construct a new ChildProcess.

  • @param args — The argv for the process. The first entry in this array is the program to run.
  • @param options — Options for the process (cwd, env, stdio, etc)
new (args: string | Path | Array<string | number | Path>, options?: ChildProcessOptions): ChildProcess;

ChildProcessConstructor.prototype (readonly ChildProcess property)​

readonly prototype: ChildProcess;

ChildProcess (ChildProcessConstructor)​

var ChildProcess: ChildProcessConstructor;