wrong description of Status for receiving a signal of interrupt

[FLAGLORD]

cmd/cmd.go

Lines 108 to 134 in 500562c

	// Status represents the running status and consolidated return of a Cmd. It can
	// be obtained any time by calling Cmd.Status. If StartTs > 0, the command has
	// started. If StopTs > 0, the command has stopped. After the command finishes
	// for any reason, this combination of values indicates success (presuming the
	// command only exits zero on success):
	//
	// Exit = 0
	// Error = nil
	// Complete = true
	//
	// Error is a Go error from the underlying os/exec.Cmd.Start or os/exec.Cmd.Wait.
	// If not nil, the command either failed to start (it never ran) or it started
	// but was terminated unexpectedly (probably signaled). In either case, the
	// command failed. Callers should check Error first. If nil, then check Exit and
	// Complete.
	type Status struct {
	Cmd string
	PID int
	Complete bool // false if stopped or signaled
	Exit int // exit code of process
	Error error // Go error
	StartTs int64 // Unix ts (nanoseconds), zero if Cmd not started
	StopTs int64 // Unix ts (nanoseconds), zero if Cmd not started or running
	Runtime float64 // seconds, zero if Cmd not started
	Stdout []string // buffered STDOUT; see Cmd.Status for more info
	Stderr []string // buffered STDERR; see Cmd.Status for more info
	}

Its description mentions that Complete should be false and Error should not be nil if signaled.
But if the underlying cmd receives a os.Interrupt signal, the returned status will have a true value in Complete and a nil value in Error

Reproduce:

test script count_sec.sh

#!/bin/sh

exit_fn () {
    # https://unix.stackexchange.com/questions/447229/how-can-we-set-up-a-signal-trap-to-be-sig-ign-and-sig-dfl-in-bash
    trap - INT              # Restore signal handling for SIGINT
    echo; echo 'Catch it! Interrupt!'    # Growl at user,
    # Mock
    # https://unix.stackexchange.com/a/99117
    exit 130                    # then exit script.
}

trap "exit_fn" INT   # Set up SIGINT trap to call function.

count=0
while [ "$1" -ne "$count" ]
do
    sleep 1
    count=$((count + 1))
    echo $count
done

trap - INT  # Restore signal handling to previous before exit.

main function:

cmd := cmd.NewCmd("sh", "count_sec.sh", "5")

time.AfterFunc(time.Second*2, func() {
	p, err := os.FindProcess(cmd.Status().PID)
	if err != nil {
		fmt.Println(err)
		return
	}
	err = p.Signal(os.Interrupt)
	if err != nil {
		fmt.Println(err)
		return
	}
})
status := <-cmd.Start()
fmt.Println(status.Stdout)
fmt.Println(status.Complete)
fmt.Println(status.Error)

[daniel-nichter]

Thanks for the report. I'll look into it.

[daniel-nichter]

Ah, SIGINT: it doesn't terminate a problem, just interrupts it. https://www.gnu.org/software/bash/manual/html_node/Signals.html

In this case, the shell script above catches that and ends the program. So the go-cmd result is correct: no error, no (handled) signal, completed, and exit status = 130.

The docs mention,

but was terminated unexpectedly (probably signaled)

The subtleness there is "unexpectedly". Catching SIGINT and terminating is not unexpected. (For example, the program could catch and keep running, instead.)

I added 0986371 to address this for future users.