Improve the documentation for exit codes in Process

sdk/lib/io/process.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 // TODO(ager): The only reason for this class is that we
 // cannot patch a top-level at this point.
 class _ProcessUtils {
   external static void _exit(int status);
   external static void _setExitCode(int status);
   external static void _sleep(int millis);
   external static int _pid(Process process);
 }
 
 /**
- * Exit the Dart VM process immediately with the given [status] code.
+ * Exit the Dart VM process immediately with the given exit code.
  *
  * This does not wait for any asynchronous operations to terminate. Using
  * [exit] is therefore very likely to lose data.
+ *
+ * The handling of exit codes is platform specific.
+ *
+ * On Linux and Mac OS an exit code for normal termination will always
+ * be in the range [0..255]. If an exit code outside this range is
+ * set the actual exit code will be the lower 8 bits masked off and
+ * treated as an unsigned value. E.g. using an exit code of -1 will
+ * result in an actual exit code of 255 being reported.
+ *
+ * On Windows the exit code can be set to any 32-bit value. However
+ * some of these values are reserved for reporting system errors like
+ * crashes.
+ *
+ * Besides this the Dart executable itself uses an exit code of `254`
+ * for reporting compile time errors and an exit code of `255` for
+ * reporting runtime error (unhandled exception).
+ *
+ * Due to these facts it is recommended to only use exit codes in the
+ * range [0..127] for communicating the result of running a Dart
+ * program to the surrounding environment. This will avoid any
+ * cross-platform issues.
  */
-void exit(int status) {
+void exit(int code) {
   if (status is !int) {
     throw new ArgumentError("exit: int status expected");
   }
   _ProcessUtils._exit(status);
 }
 
 /**
  * Global exit code for the Dart VM.
  *
  * The exit code is global for the Dart VM and the last assignment to
  * exitCode from any isolate determines the exit code of the Dart VM
  * on normal termination.
+ *
+ * See [exit] for more information on how to chose a value for the
+ * exit code.
  */
-set exitCode(int status) {
+set exitCode(int code) {
   if (status is !int) {
     throw new ArgumentError("setExitCode: int status expected");
   }
   _ProcessUtils._setExitCode(status);
 }
 
 /**
  * Sleep for the duration specified in [duration].
  *
  * Use this with care, as no asynchronous operations can be processed
@@ skipping 131 matching lines @@
       List<String> arguments,
       {String workingDirectory,
        Map<String, String> environment,
        bool includeParentEnvironment: true,
        bool runInShell: false,
        Encoding stdoutEncoding: SYSTEM_ENCODING,
        Encoding stderrEncoding: SYSTEM_ENCODING});
 
   /**
    * 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.
+   * The handling of exit codes is platform specific.
+   *
+   * On Linux and Mac a normal exit code will be a positive value in
+   * the range [0..255]. If the process was terminated due to a signal
+   * the exit code will be a negative value in the range [-255..0[,
+   * where the absolute value of the exit code is the signal
+   * number. For example, if a process crashes due to a segmentation
+   * violation the exit code will be -11, as the signal SIGSEGV has the
+   * number 11.
+   *
+   * On Windows a process can report any 32-bit value as an exit
+   * code. When returning the exit code this exit code is turned into
+   * a signed value. Some special values are used to report
+   * termination due to some system event. E.g. if a process crashes
+   * due to an access violation the 32-bit exit code is `0xc0000005`,
+   * which will be returned as the negative number `-1073741819`. To
+   * get the original 32-bit value use `(0x100000000 + exitCode) &
+   * 0xffffffff`.
    */
   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]);
 }
 
 
 /**
  * [ProcessResult] represents the result of running a non-interactive
  * process started with [:Process.run:].
  */
 abstract class ProcessResult {
   /**
    * Exit code for the process.
+   *
+   * See [Process.exitCode] for more information in the exit code
+   * value.
    */
   int get exitCode;
 
   /**
    * Standard output from the process. The value used for the
    * `stdoutEncoding` argument to `Process.run` determins the type. If
    * `null` was used this value is of type `List<int> otherwise it is
    * of type `String`.
    */
   get stdout;
@@ skipping 76 matching lines @@
   /**
    * Contains the system message for the process exception if any.
    */
   final String message;
 
   /**
    * Contains the OS error code for the process exception if any.
    */
   final int errorCode;
 }