Process class Null safety
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.
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');
}
Constructors
- Process()
Properties
-
exitCode
→ Future<
int> -
A
Future
which completes with the exit code of the process when the process completes.read-only - hashCode → int
-
The hash code for this object.
read-only, inherited
- pid → int
-
The process id of the process.
read-only
- runtimeType → Type
-
A representation of the runtime type of the object.
read-only, inherited
-
stderr
→ Stream<
List< int> > -
The standard error stream of the process as a
Stream
.read-only - stdin → IOSink
-
The standard input stream of the process as an IOSink.
read-only
-
stdout
→ Stream<
List< int> > -
The standard output stream of the process as a
Stream
.read-only
Methods
-
kill(
[ProcessSignal signal = ProcessSignal.sigterm]) → bool - Kills the process.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a non-existent 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 specifiedarguments
. -
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 specifiedarguments
.