description

# Process class abstract interface

The means to execute a program.

Use the static start and run methods to start a new process. The run method executes the process non-interactively to completion. In contrast, the start method allows your code to interact with the running process.

## Start a process with the run method

The following code sample uses the run method to create a process that runs the UNIX command `ls`, which lists the contents of a directory. The run method completes with a ProcessResult object when the process terminates. This provides access to the output and exit code from the process. The run method does not return a `Process` object; this prevents your code from interacting with the running process.

    import 'dart:io';

    main() async {
      // List all files in the current directory in UNIX-like systems.
      var result = await Process.run('ls', ['-l']);
      print(result.stdout);
    }

## Start a process with the start method

The following example uses start to create the process. The start method returns a Future for a `Process` object. When the future completes the process is started and your code can interact with the process: writing to stdin, listening to stdout, and so on.

The following sample starts the UNIX `cat` utility, which when given no command-line arguments, echos its input. The program writes to the process's standard input stream and prints data from its standard output stream.

    import 'dart:io';
    import 'dart:convert';

    main() async {
      var process = await Process.start('cat', []);
      process.stdout
          .transform(utf8.decoder)
          .forEach(print);
      process.stdin.writeln('Hello, world!');
      process.stdin.writeln('Hello, galaxy!');
      process.stdin.writeln('Hello, universe!');
    }

## Standard I/O streams

As seen in the previous code sample, you can interact with the `Process`'s standard output stream through the getter stdout, and you can interact with the `Process`'s standard input stream through the getter stdin. In addition, `Process` provides a getter stderr for using the `Process`'s standard error stream.

A `Process`'s streams are distinct from the top-level streams for the current program.

NOTE: `stdin`, `stdout`, and `stderr` are implemented using pipes between the parent process and the spawned subprocess. These pipes have limited capacity. If the subprocess writes to stderr or stdout in excess of that limit without the output being read, the subprocess blocks waiting for the pipe buffer to accept more data. For example:

    import 'dart:io';

    main() async {
      var process = await Process.start('cat', ['largefile.txt']);
      // The following await statement will never complete because the
      // subprocess never exits since it is blocked waiting for its
      // stdout to be read.
      await process.stderr.forEach(print);
    }

## Exit codes

Call the exitCode method to get the exit code of the process. The exit code indicates whether the program terminated successfully (usually indicated with an exit code of 0) or with an error.

If the start method is used, the exitCode is available through a future on the `Process` object (as shown in the example below). If the run method is used, the exitCode is available through a getter on the ProcessResult instance.

    import 'dart:io';

    main() async {
      var process = await Process.start('ls', ['-l']);
      var exitCode = await process.exitCode;
      print('exit code: $exitCode');
    }

## Properties

exitCode → Future<int>
  A `Future` which completes with the exit code of the process when the process completes.
  no setter
hashCode → int
  The hash code for this object.
  no setter inherited
pid → int
  The process id of the process.
  no setter
runtimeType → Type
  A representation of the runtime type of the object.
  no setter inherited
stderr → Stream<List<int>>
  The standard error stream of the process as a `Stream`.
  no setter
stdin → IOSink
  The standard input stream of the process as an IOSink.
  no setter
stdout → Stream<List<int>>
  The standard output stream of the process as a `Stream`.
  no setter

## Methods

kill([ProcessSignal signal = ProcessSignal.sigterm]) → bool
  Kills the process.
noSuchMethod(Invocation invocation) → dynamic
  Invoked when a nonexistent method or property is accessed.
  inherited
toString() → String
  A string representation of this object.
  inherited

## Operators

operator ==(Object other) → bool
  The equality operator.
  inherited

## Static Methods

killPid(int pid, [ProcessSignal signal = ProcessSignal.sigterm]) → bool
  Kills the process with id `pid`.
run(String executable, List<String> arguments, {String? workingDirectory, Map<String, String>? environment, bool includeParentEnvironment = true, bool runInShell = false, Encoding? stdoutEncoding = systemEncoding, Encoding? stderrEncoding = systemEncoding}) → Future<ProcessResult>
  Starts a process and runs it non-interactively to completion. The process run is `executable` with the specified `arguments`.
runSync(String executable, List<String> arguments, {String? workingDirectory, Map<String, String>? environment, bool includeParentEnvironment = true, bool runInShell = false, Encoding? stdoutEncoding = systemEncoding, Encoding? stderrEncoding = systemEncoding}) → ProcessResult
  Starts a process and runs it to completion. This is a synchronous call and will block until the child process terminates.
start(String executable, List<String> arguments, {String? workingDirectory, Map<String, String>? environment, bool includeParentEnvironment = true, bool runInShell = false, ProcessStartMode mode = ProcessStartMode.normal}) → Future<Process>
  Starts a process running the `executable` with the specified `arguments`.