os: Document Exit() behavior with code outside 0 - 255

[cuonglm]

What version of Go are you using (go version)?

$ go version
go version go1.12.1 linux/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/cuonglm/.cache/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/home/cuonglm/go"
GOPROXY=""
GORACE=""
GOROOT="/usr/local/stow/go"
GOTMPDIR=""
GOTOOLDIR="/usr/local/stow/go/pkg/tool/linux_amd64"
GCCGO="gccgo"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/home/cuonglm/sources/go/src/go.mod"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build303772017=/tmp/go-build -gno-record-gcc-switches"

What did you do?

package main

import "os"

func main() {
	os.Exit(256)
}

Compile program then run:

./main || echo ./main should return failure code

What did you expect to see?

./main should return failure code is printed in terminal.

What did you see instead?

No output.

The number 256 is passed as-is to _exit(), or in my case exit_group() on Linux.

But on Linux, and other systems which use traditional wait*() system call, only the lower 8 bits of that number are available to the parent. it means the program above appears as success.

If the parent uses waitid(), the number won't be truncated and return as-is to the parent (Though not on Linux, which still truncate the number even waitid() was used. The behavior maybe change in the future).

So the behavior of os.Exit(code) where code > 255 or code < 0 can not be consistent. I propose one of these changes:

• Always transform the code like wait*() does, mean a value between 0-255 always returns to parent.

• Limit the code to value between 0 - 255, do something in case the code out of range:

  • warning message that value outside of 0 - 255 can be truncated
  • warning message that value outside of 0 - 255 is bad number (like dash, yash does)
  • panic, so user knows the problem, and get a standard error code from panic. It also does not break any program. (like m4 does)

• Document that only value between 0 - 255 is consistent and should be used. Value greater than 255 may or may not be truncated, so the exit code is unspecified.

[cuonglm]

cc @ianlancetaylor @rsc @robpike @bradfitz

[robpike]

I resist documenting the operating systems themselves, but in this case it seems reasonable to document that valid values range from 0 to 255. There's nothing to do in the implementation that makes any sense: we're exiting anyway.

[gopherbot]

Change https://golang.org/cl/169357 mentions this issue: os: document exit status range value