From 62c0f4dbd85a78f50ba99082c56a1a70d92e67e9 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Wed, 26 Feb 2020 13:26:30 -0800 Subject: [PATCH 1/3] 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 --- phases/ephemeral/witx/typenames.witx | 16 ++++++++++++++-- phases/ephemeral/witx/wasi_ephemeral_proc.witx | 9 ++++++--- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/phases/ephemeral/witx/typenames.witx b/phases/ephemeral/witx/typenames.witx index 1f9abc59..1d20bf38 100644 --- a/phases/ephemeral/witx/typenames.witx +++ b/phases/ephemeral/witx/typenames.witx @@ -638,8 +638,20 @@ ) ) -;;; Exit code generated by a process when exiting. -(typename $exitcode u32) +;;; Exit code generated by a program when exiting. +(typename $exitcode + (int u8 + ;;; Indicate the program exited successfully. + ;;; + ;;; Note: This is similar to `EXIT_SUCCESS` in POSIX. + (const $success 0) + + ;;; Indicate the program exited unsuccessfully. + ;;; + ;;; Note: This is similar to `EXIT_FAILURE` in POSIX. + (const $failure 1) + ) +) ;;; Flags provided to `sock_recv`. (typename $riflags diff --git a/phases/ephemeral/witx/wasi_ephemeral_proc.witx b/phases/ephemeral/witx/wasi_ephemeral_proc.witx index 0507d4ff..0a8f65a1 100644 --- a/phases/ephemeral/witx/wasi_ephemeral_proc.witx +++ b/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 at least 126 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) From e1f207de23336620769c7ea793adb5fc5accbf18 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Wed, 26 Feb 2020 16:03:21 -0800 Subject: [PATCH 2/3] Update the docs. --- phases/ephemeral/docs.md | 9 ++++++--- phases/ephemeral/witx/typenames.witx | 22 ++++++++++------------ 2 files changed, 16 insertions(+), 15 deletions(-) diff --git a/phases/ephemeral/docs.md b/phases/ephemeral/docs.md index e7a3aa91..2496f7da 100644 --- a/phases/ephemeral/docs.md +++ b/phases/ephemeral/docs.md @@ -2389,9 +2389,12 @@ The number of events stored. --- #### `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 at least 126 is given, this function behaves as if it were +implemented by an `unreachable` instruction. ##### Params - `rval`: [`exitcode`](#exitcode) diff --git a/phases/ephemeral/witx/typenames.witx b/phases/ephemeral/witx/typenames.witx index 1d20bf38..bbd6489d 100644 --- a/phases/ephemeral/witx/typenames.witx +++ b/phases/ephemeral/witx/typenames.witx @@ -639,19 +639,17 @@ ) ;;; Exit code generated by a program when exiting. -(typename $exitcode - (int u8 - ;;; Indicate the program exited successfully. - ;;; - ;;; Note: This is similar to `EXIT_SUCCESS` in POSIX. - (const $success 0) +(typename $exitcode u8) - ;;; Indicate the program exited unsuccessfully. - ;;; - ;;; Note: This is similar to `EXIT_FAILURE` in POSIX. - (const $failure 1) - ) -) +;;; 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 From 17a25e739924fef43a727ec2d2d557bccb894612 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Wed, 26 Feb 2020 16:36:21 -0800 Subject: [PATCH 3/3] Say "or greater" instead of "at least". --- phases/ephemeral/docs.md | 2 +- phases/ephemeral/witx/wasi_ephemeral_proc.witx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/phases/ephemeral/docs.md b/phases/ephemeral/docs.md index 2496f7da..555d74e2 100644 --- a/phases/ephemeral/docs.md +++ b/phases/ephemeral/docs.md @@ -2393,7 +2393,7 @@ 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 at least 126 is given, this function behaves as if it were +of 126 or greater is given, this function behaves as if it were implemented by an `unreachable` instruction. ##### Params diff --git a/phases/ephemeral/witx/wasi_ephemeral_proc.witx b/phases/ephemeral/witx/wasi_ephemeral_proc.witx index 0a8f65a1..0bd57682 100644 --- a/phases/ephemeral/witx/wasi_ephemeral_proc.witx +++ b/phases/ephemeral/witx/wasi_ephemeral_proc.witx @@ -12,7 +12,7 @@ ;;; 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 at least 126 is given, this function behaves as if it were + ;;; 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.