New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

os, os/signal: inconsistent documentation #27854

Open
kevinburke opened this Issue Sep 25, 2018 · 3 comments

Comments

Projects
None yet
3 participants
@kevinburke
Contributor

kevinburke commented Sep 25, 2018

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

This comment has been minimized.

Contributor

ianlancetaylor commented Sep 25, 2018

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

This comment has been minimized.

gopherbot commented Sep 25, 2018

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

@kevinburke

This comment has been minimized.

Contributor

kevinburke commented Sep 25, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment