Dart API Referencedart:ioProcess

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 int pid #

Returns the process id of the process.

int get pid;

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;

final IOSink stdin #

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

Throws an UnsupportedError if the process is non-interactive.

IOSink get stdin;

final Stream<List<int>> stdout #

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;

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.