os, os/signal: inconsistent documentation

[kevinburke]

I'm trying to define cleanup behavior in a Windows program, so I want to catch a signal, do some cleanup, and then exit the program. I don't have a Windows machine though so testing this is sort of tricky.

The docs for os.Interrupt state:

The only signal values guaranteed to be present in the os package on all systems are Interrupt (send the process an interrupt) and Kill (force the process to exit). Interrupt is not implemented on Windows; using it with os.Process.Signal will return an error.

However, the docs for os/signal state, under the Windows section:

On Windows a ^C (Control-C) or ^BREAK (Control-Break) normally cause the program to exit. If Notify is called for os.Interrupt, ^C or ^BREAK will cause os.Interrupt to be sent on the channel, and the program will not exit.

I'm confused how Interrupt can be all of:

• guaranteed to be present
• not implemented
• calling Notify() can cause it to be sent on the channel when a user hits ^BREAK

Searching the os package source code for Interrupt seems to show it's only defined for unix/posix GOOS's and not for Windows. It might be nice to add a short doc to the os package explaining how it gets sent (if I am reading correctly, from runtime/os_windows.go:ctrlhandler1 and runtime/sigqueue.go:sigsend).

[ianlancetaylor]

os.Interrupt is defined on Windows in os/exec_posix.go, set to syscall.SIGINT (yes, it can be confusing to treat Windows as a POSIX system).

os.Interrupt is not implemented for use with os.Process.Signal. But it is still, I believe, true that if the user hits ^C or ^BREAK that os.Interrupt (really syscall.SIGINT) will be sent on a channel registered using signal.Notify.

So while the documentation is confusing and should be cleaned up, I think that it is in essence correct.

[gopherbot]

Change https://golang.org/cl/137336 mentions this issue: os: clearer doc for Interrupt

[kevinburke]

Yeah, I missed that "not implemented" refers specifically to os.Process.Signal(os.Interrupt) and not to the entire variable. I just submitted a change to try to clear things up.