Disallow non-portable and signal values as exit statuses. (#235)

* Disallow non-portable and signal values as exit statuses.

Exit codes of at least 256 aren't portable to [POSIX exit], so
programs expecting to return full 32-bit [Windows System Error Codes]
aren't practically portable.

And on POSIX, error codes of at least 128 are reserved for reporting
program exits via signals, and 127 and 126 are reserved for POSIX-style
shells. While it's theoretically possible for POSIX applications to
return these explicitly, this is very rare, not often useful,
particularly in programs intended to be portable, and could potentially
be confusing to users.

If a need arrises for programs to return values in [126,256), or to
provide other kinds of information upon program exit, we can look at
relaxing these restrictions or adding new APIs to WASI for program
termination, but for now it makes sense to start with something simple.

With that, this PR proposes:
 - The WASI `exit` function takes a `u8`, but if the value is at
   least 126, it traps. Otherwise it is provided to the environment.
 - WASI libc's `exit` will map from `int` to `u8` by applying the mask
   as specified in [POSIX exit].

No other WASI syscalls trap right now, but `exit` has no other way to
indicate errors.

[POSIX exit]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/_Exit.html
[Windows System Error Codes]: https://docs.microsoft.com/en-us/windows/win32/debug/system-error-codes?redirectedfrom=MSDN#system-error-codes

* Update the docs.

* Say "or greater" instead of "at least".

Co-authored-by: Dan Gohman <[email protected]>

Author: sunfishcode

phases/ephemeral/docs.md

@@ -2389,9 +2389,12 @@ The number of events stored.
 ---
 
 #### <a href="#exit" name="exit"></a> `exit(rval: exitcode)`
-Terminate the process normally. An exit code of 0 indicates successful
-termination of the program. The meanings of other values is dependent on
-the environment.
+Terminate the process normally. An exit code of `$exitcode::success`
+reports successful completion of the program. An exit code of
+`$exitcode::failure` or any other value less than 126 reports a
+failure, and the value is provided to the environment. If a value
+of 126 or greater is given, this function behaves as if it were
+implemented by an `unreachable` instruction.
 
 ##### Params
 - <a href="#exit.rval" name="exit.rval"></a> `rval`: [`exitcode`](#exitcode)

phases/ephemeral/witx/typenames.witx

@@ -638,8 +638,18 @@
   )
 )
 
-;;; Exit code generated by a process when exiting.
-(typename $exitcode u32)
+;;; Exit code generated by a program when exiting.
+(typename $exitcode u8)
+
+;;; Indicate the program exited successfully.
+;;;
+;;; Note: This is similar to `EXIT_SUCCESS` in POSIX.
+(@witx const $exitcode $success 0)
+
+;;; Indicate the program exited unsuccessfully.
+;;;
+;;; Note: This is similar to `EXIT_FAILURE` in POSIX.
+(@witx const $exitcode $failure 1)
 
 ;;; Flags provided to `sock_recv`.
 (typename $riflags

phases/ephemeral/witx/wasi_ephemeral_proc.witx

@@ -8,9 +8,12 @@
 (use "typenames.witx")
 
 (module $wasi_ephemeral_proc
-  ;;; Terminate the process normally. An exit code of 0 indicates successful
-  ;;; termination of the program. The meanings of other values is dependent on
-  ;;; the environment.
+  ;;; Terminate the process normally. An exit code of `$exitcode::success`
+  ;;; reports successful completion of the program. An exit code of
+  ;;; `$exitcode::failure` or any other value less than 126 reports a
+  ;;; failure, and the value is provided to the environment. If a value
+  ;;; of 126 or greater is given, this function behaves as if it were
+  ;;; implemented by an `unreachable` instruction.
   (@interface func (export "exit")
     ;;; The exit code returned by the process.
     (param $rval $exitcode)