OLD | NEW |
1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 part of dart.io; | 5 part of dart.io; |
6 | 6 |
7 // TODO(ager): The only reason for this class is that we | 7 // TODO(ager): The only reason for this class is that we |
8 // cannot patch a top-level at this point. | 8 // cannot patch a top-level at this point. |
9 class _ProcessUtils { | 9 class _ProcessUtils { |
10 external static void _exit(int status); | 10 external static void _exit(int status); |
(...skipping 67 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
78 } | 78 } |
79 _ProcessUtils._sleep(milliseconds); | 79 _ProcessUtils._sleep(milliseconds); |
80 } | 80 } |
81 | 81 |
82 /** | 82 /** |
83 * Returns the PID of the current process. | 83 * Returns the PID of the current process. |
84 */ | 84 */ |
85 int get pid => _ProcessUtils._pid(null); | 85 int get pid => _ProcessUtils._pid(null); |
86 | 86 |
87 /** | 87 /** |
88 * [Process] is used to start new processes using the static | 88 * The means to execute a program. |
89 * [start] and [run] methods. | 89 * |
| 90 * Use the static [start] and [run] methods to start a new process. |
| 91 * The run method executes the process non-interactively to completion. |
| 92 * In contrast, the start method allows your code to interact with the |
| 93 * running process. |
| 94 * |
| 95 * ## Start a process with the run method |
| 96 * |
| 97 * The following code sample uses the run method to create a process |
| 98 * that runs the UNIX command `ls`, which lists the contents of a directory. |
| 99 * The run method completes with a [ProcessResult] object when the process |
| 100 * terminates. This provides access to the output and exit code from the |
| 101 * process. The run method does not return a Process object; this prevents your |
| 102 * code from interacting with the running process. |
| 103 * |
| 104 * import 'dart:io'; |
| 105 * |
| 106 * main() { |
| 107 * // List all files in the current directory in UNIX-like systems. |
| 108 * Process.run('ls', ['-l']).then((ProcessResult results) { |
| 109 * print(results.stdout); |
| 110 * }); |
| 111 * } |
| 112 * |
| 113 * ## Start a process with the start method |
| 114 * |
| 115 * The following example uses start to create the process. |
| 116 * The start method returns a [Future] for a Process object. |
| 117 * When the future completes the process is started and |
| 118 * your code can interact with the |
| 119 * Process: writing to stdin, listening to stdout, and so on. |
| 120 * |
| 121 * The following sample starts the UNIX `cat` utility, which when given no |
| 122 * command-line arguments, echos its input. |
| 123 * The program writes to the process's standard input stream |
| 124 * and prints data from its standard output stream. |
| 125 * |
| 126 * import 'dart:io'; |
| 127 * import 'dart:convert'; |
| 128 * |
| 129 * main() { |
| 130 * Process.start('cat', []).then((Process process) { |
| 131 * process.stdout |
| 132 * .transform(UTF8.decoder) |
| 133 * .listen((data) { print(data); }); |
| 134 * process.stdin.writeln('Hello, world!'); |
| 135 * process.stdin.writeln('Hello, galaxy!'); |
| 136 * process.stdin.writeln('Hello, universe!'); |
| 137 * }); |
| 138 * } |
| 139 * |
| 140 * ## Standard I/O streams |
| 141 * |
| 142 * As seen in the previous code sample, you can interact with the Process's |
| 143 * standard output stream through the getter [stdout], |
| 144 * and you can interact with the Process's standard input stream through |
| 145 * the getter [stdin]. |
| 146 * In addition, Process provides a getter [stderr] for using the Process's |
| 147 * standard error stream. |
| 148 * |
| 149 * A Process's streams are distinct from the top-level streams |
| 150 * for the current program. |
| 151 * |
| 152 * ## Exit codes |
| 153 * |
| 154 * Call the [exitCode] method to get the exit code of the process. |
| 155 * The exit code indicates whether the program terminated successfully |
| 156 * (usually indicated with an exit code of 0) or with an error. |
| 157 * |
| 158 * If the start method is used, the exitCode is available through a future |
| 159 * on the Process object (as shown in the example below). |
| 160 * If the run method is used, the exitCode is available |
| 161 * through a getter on the ProcessResult instance. |
| 162 * |
| 163 * import 'dart:io'; |
| 164 * |
| 165 * main() { |
| 166 * Process.start('ls', ['-l']).then((process) { |
| 167 * // Get the exit code from the new process. |
| 168 * process.exitCode.then((exitCode) { |
| 169 * print('exit code: $exitCode'); |
| 170 * }); |
| 171 * }); |
| 172 * } |
| 173 * |
| 174 * ## Other resources |
| 175 * |
| 176 * [Dart by Example](https://www.dartlang.org/dart-by-example/#dart-io-and-comma
nd-line-apps) |
| 177 * provides additional task-oriented code samples that show how to use |
| 178 * various API from the [dart:io] library. |
90 */ | 179 */ |
91 abstract class Process { | 180 abstract class Process { |
92 /** | 181 /** |
93 * Returns a [:Future:] which completes with the exit code of the process | 182 * Returns a [:Future:] which completes with the exit code of the process |
94 * when the process completes. | 183 * when the process completes. |
95 * | 184 * |
96 * The handling of exit codes is platform specific. | 185 * The handling of exit codes is platform specific. |
97 * | 186 * |
98 * On Linux and Mac a normal exit code will be a positive value in | 187 * On Linux and Mac a normal exit code will be a positive value in |
99 * the range [0..255]. If the process was terminated due to a signal | 188 * the range [0..255]. If the process was terminated due to a signal |
(...skipping 302 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
402 final int errorCode; | 491 final int errorCode; |
403 | 492 |
404 const ProcessException(this.executable, this.arguments, [this.message = "", | 493 const ProcessException(this.executable, this.arguments, [this.message = "", |
405 this.errorCode = 0]); | 494 this.errorCode = 0]); |
406 String toString() { | 495 String toString() { |
407 var msg = (message == null) ? 'OS error code: $errorCode' : message; | 496 var msg = (message == null) ? 'OS error code: $errorCode' : message; |
408 var args = arguments.join(' '); | 497 var args = arguments.join(' '); |
409 return "ProcessException: $msg\n Command: $executable $args"; | 498 return "ProcessException: $msg\n Command: $executable $args"; |
410 } | 499 } |
411 } | 500 } |
OLD | NEW |