Process abstract class
Process is used to start new processes using the static start and run methods.
abstract class 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.
*
* Use [workingDirectory] to set the working directory for the process. Note
* that the change of directory occurs before executing the process on some
* platforms, which may have impact when using relative paths for the
* executable and the arguments.
*
* Use [environment] to set the environment variables for the process. If not
* set the environment of the parent process is inherited. Currently, only
* US-ASCII environment variables are supported and errors are likely to occur
* if an environment variable with code-points outside the US-ASCII range is
* passed in.
*
* If [runInShell] is true, the process will be spawned through a system
* shell. On Linux and Mac OS, [:/bin/sh:] is used, while
* [:%WINDIR%\system32\cmd.exe:] is used on Windows.
*
* Users must read all data coming on the [stdout] and [stderr]
* streams of processes started with [:Process.start:]. If the user
* does not read all data on the streams the underlying system
* resources will not be freed since there is still pending data.
*/
external static Future<Process> start(
String executable,
List<String> arguments,
{String workingDirectory,
Map<String, String> environment,
bool runInShell: false});
/**
* Starts a process and runs it non-interactively to completion. The
* process run is [executable] with the specified [arguments].
*
* Use [workingDirectory] to set the working directory for the process. Note
* that the change of directory occurs before executing the process on some
* platforms, which may have impact when using relative paths for the
* executable and the arguments.
*
* Use [environment] to set the environment variables for the process. If not
* set the environment of the parent process is inherited. Currently, only
* US-ASCII environment variables are supported and errors are likely to occur
* if an environment variable with code-points outside the US-ASCII range is
* passed in.
*
* If [runInShell] is true, the process will be spawned through a system
* shell. On Linux and Mac OS, [:/bin/sh:] is used, while
* [:%WINDIR%\system32\cmd.exe:] is used on Windows.
*
* The encoding used for text on stdout and stderr can be set by changing
* [stdoutEncoding] and [stderrEncoding]. The default encoding is SYSTEM.
*
* Returns a [:Future<ProcessResult>:] that completes with the
* result of running the process, i.e., exit code, standard out and
* standard in.
*/
external static Future<ProcessResult> run(
String executable,
List<String> arguments,
{String workingDirectory,
Map<String, String> environment,
bool runInShell: false,
Encoding stdoutEncoding: Encoding.SYSTEM,
Encoding stderrEncoding: Encoding.SYSTEM});
/**
* Returns the standard output stream of the process as a [:Stream:].
*
* Throws an [UnsupportedError] if the process is
* non-interactive.
*/
Stream<List<int>> get stdout;
/**
* Returns the standard error stream of the process as a [:Stream:].
*
* Throws an [UnsupportedError] if the process is
* non-interactive.
*/
Stream<List<int>> get stderr;
/**
* Returns the standard input stream of the process as an [IOSink].
*
* Throws an [UnsupportedError] if the process is
* non-interactive.
*/
IOSink get stdin;
/**
* Returns the process id of the process.
*/
int get pid;
/**
* Returns a [:Future:] which completes with the exit code of the process
* when the process completes.
*
* Throws an [UnsupportedError] if the process is
* non-interactive.
*/
Future<int> exitCode;
/**
* On Windows, [kill] kills the process, ignoring the [signal]
* flag. On Posix systems, [kill] sends [signal] to the
* process. Depending on the signal giving, it'll have different
* meanings. When the process terminates as a result of calling
* [kill] [onExit] is called.
*
* Returns [:true:] if the process is successfully killed (the
* signal is successfully sent). Returns [:false:] if the process
* could not be killed (the signal could not be sent). Usually,
* a [:false:] return value from kill means that the process is
* already dead.
*/
bool kill([ProcessSignal signal = ProcessSignal.SIGTERM]);
}
Static Methods
Future<Process> start(String executable, List<String> arguments, {String workingDirectory, Map<String, String> environment, bool runInShell: false}) #
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.
Use workingDirectory to set the working directory for the process. Note that the change of directory occurs before executing the process on some platforms, which may have impact when using relative paths for the executable and the arguments.
Use environment to set the environment variables for the process. If not set the environment of the parent process is inherited. Currently, only US-ASCII environment variables are supported and errors are likely to occur if an environment variable with code-points outside the US-ASCII range is passed in.
If
runInShell is true, the process will be spawned through a system
shell. On Linux and Mac OS, /bin/sh is used, while
%WINDIR%\system32\cmd.exe is used on Windows.
Users must read all data coming on the stdout and stderr
streams of processes started with Process.start. If the user
does not read all data on the streams the underlying system
resources will not be freed since there is still pending data.
external static Future<Process> start(
String executable,
List<String> arguments,
{String workingDirectory,
Map<String, String> environment,
bool runInShell: false});
Future<ProcessResult> run(String executable, List<String> arguments, {String workingDirectory, Map<String, String> environment, bool runInShell: false, Encoding stdoutEncoding: Encoding.SYSTEM, Encoding stderrEncoding: Encoding.SYSTEM}) #
Starts a process and runs it non-interactively to completion. The process run is executable with the specified arguments.
Use workingDirectory to set the working directory for the process. Note that the change of directory occurs before executing the process on some platforms, which may have impact when using relative paths for the executable and the arguments.
Use environment to set the environment variables for the process. If not set the environment of the parent process is inherited. Currently, only US-ASCII environment variables are supported and errors are likely to occur if an environment variable with code-points outside the US-ASCII range is passed in.
If
runInShell is true, the process will be spawned through a system
shell. On Linux and Mac OS, /bin/sh is used, while
%WINDIR%\system32\cmd.exe is used on Windows.
The encoding used for text on stdout and stderr can be set by changing stdoutEncoding and stderrEncoding. The default encoding is SYSTEM.
Returns a Future<ProcessResult> that completes with the
result of running the process, i.e., exit code, standard out and
standard in.
external static Future<ProcessResult> run(
String executable,
List<String> arguments,
{String workingDirectory,
Map<String, String> environment,
bool runInShell: false,
Encoding stdoutEncoding: Encoding.SYSTEM,
Encoding stderrEncoding: Encoding.SYSTEM});
Properties
Future<int> exitCode #
Returns a Future which completes with the exit code of the process
when the process completes.
Throws an UnsupportedError if the process is
non-interactive.
Future<int> exitCode
final Stream<List<int>> stderr #
Returns the standard error stream of the process as a Stream.
Throws an UnsupportedError if the process is
non-interactive.
Stream<List<int>> get stderr;
Methods
abstract bool kill([ProcessSignal signal = ProcessSignal.SIGTERM]) #
On Windows, kill kills the process, ignoring the signal flag. On Posix systems, kill sends signal to the process. Depending on the signal giving, it'll have different meanings. When the process terminates as a result of calling [kill] [onExit] is called.
Returns true if the process is successfully killed (the
signal is successfully sent). Returns false if the process
could not be killed (the signal could not be sent). Usually,
a false return value from kill means that the process is
already dead.