dart:io

Process class

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() {
  // List all files in the current directory in UNIX-like systems.
  Process.run('ls', ['-l']).then((ProcessResult results) {
    print(results.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() {
  Process.start('cat', []).then((Process process) {
    process.stdout
        .transform(utf8.decoder)
        .listen((data) { print(data); });
    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.

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() {
  Process.start('ls', ['-l']).then((process) {
    // Get the exit code from the new process.
    process.exitCode.then((exitCode) {
      print('exit code: $exitCode');
    });
  });
}

Other resources

Dart by Example provides additional task-oriented code samples that show how to use various API from the dart:io library.

Constructors

Process()

Properties

exitCode → Future<int>

read-only

Returns a Future which completes with the exit code of the process when the process completes. [...]

pid → int

read-only

Returns the process id of the process.

stderr → Stream<List<int>>

read-only

Returns the standard error stream of the process as a Stream.

stdin → IOSink

read-only

Returns the standard input stream of the process as an IOSink.

stdout → Stream<List<int>>

read-only

Returns the standard output stream of the process as a Stream.

hashCode → int

read-only, inherited

The hash code for this object. [...]

runtimeType → Type

read-only, inherited

A representation of the runtime type of the object.

Methods

kill([ProcessSignal signal = ProcessSignal.sigterm ]) → bool

Kills the process. [...]

noSuchMethod(Invocation invocation) → dynamic

inherited

Invoked when a non-existent method or property is accessed. [...]

toString() → String

inherited

Returns a string representation of this object.

Operators

operator ==(dynamic other) → bool

inherited

The equality operator. [...]

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. Returns a Future<Process> that completes with a Process instance when the process has been successfully started. That Process object can be used to interact with the process. If the process cannot be started the returned Future completes with an exception. [...]