Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Logging, Flags and Testing

Go os/signal package

Reference for Go's os/signal package: Notify, NotifyContext, Stop, Ignore and Reset, with channel buffering rules and graceful shutdown patterns.

The os/signal package delivers operating system signals to your program as values on a channel. You register a channel with signal.Notify, and from then on the runtime sends a value there each time one of the chosen signals arrives. The default behavior for those signals (usually terminating the process) is replaced by your handling.

The most common use is a graceful shutdown: wait for SIGINT (Ctrl+C) or SIGTERM (sent by kill, Docker and Kubernetes), finish in-flight work, then exit. Since Go 1.16, signal.NotifyContext wraps this in a context.Context that is canceled when the signal arrives.

Go
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
<-ctx.Done() // blocks until Ctrl+C or SIGTERM

Try it

Go Catching a signal sent to ourselves

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go NotifyContext and graceful shutdown

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
func Notify(c chan<- os.Signal, sig ...os.Signal)
func NotifyContext(parent context.Context, signals ...os.Signal) (ctx context.Context, stop context.CancelFunc)
func Stop(c chan<- os.Signal)
func Ignore(sig ...os.Signal)
func Ignored(sig os.Signal) bool
func Reset(sig ...os.Signal)
Name Description
Notify(c, sig...) Relays the listed signals to c. With no signals listed, it relays every signal. Can be called again on the same channel to add more.
NotifyContext(parent, sig...) Returns a context canceled when one of the signals arrives, when stop is called, or when parent is canceled.
Stop(c) Stops relaying to c. No more values arrive, but values already in the buffer stay.
Ignore(sig...) Makes the program ignore the signals, and removes them from any channels.
Ignored(sig) Reports whether sig is currently ignored.
Reset(sig...) Cancels all Notify registrations for these signals and restores default behavior.

Returns: NotifyContext returns the derived context and a stop function you should always call (usually with defer) to release resources and restore default handling.

Edge cases: signals that cannot be caught, SIGKILL and SIGSTOP, are never delivered. On Windows only os.Interrupt (Ctrl+C) and syscall.SIGTERM are meaningful; other signals such as SIGHUP or SIGUSR1 do not exist there.

Usage notes

  • Use a buffered channel. The package never blocks when it sends. If your channel is unbuffered and nobody is receiving at that moment, the signal is dropped. A buffer of 1 is enough for one signal type; use a larger one if you watch several.
  • Which signals? os.Interrupt is SIGINT on every platform. syscall.SIGTERM is what process managers send on shutdown. Handle both.
  • Registering overrides the default. After Notify for SIGINT, Ctrl+C no longer kills the program. Make sure the receiving code eventually exits, or the process cannot be stopped from the terminal. A common trick is calling stop() right after the first signal, so a second Ctrl+C terminates immediately.
  • NotifyContext is usually better than raw Notify for servers: pass the context into http.Server.Shutdown and into your workers, as in the second example.
  • Signals in Docker. Docker sends SIGTERM to the container's main process only. Use the exec form of CMD (CMD ["./app"]) so your program is that process and not a child of a shell that swallows the signal.
  • SIGPIPE is special: writing to a closed pipe on file descriptors 1 or 2 kills the program unless you handle it; on others it just returns EPIPE.
  • Tests. Sending a signal to your own process with syscall.Kill (Unix only) is a simple way to test shutdown code.