
`signal.Notify` registers a channel to receive OS signals. `signal.NotifyContext` (Go 1.16) is the idiomatic way to tie a `context.Context` to signal receipt - when the signal arrives, the context is cancelled and the cancellation propagates through the entire call stack.

<ExamplePair>
<ExampleProse>

`signal.Notify` delivers matching signals to the channel. Always create a buffered channel (capacity 1) so the signal is not dropped if the goroutine is not ready to receive.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "os"
    "os/signal"
    "syscall"
)

func main() {
    sigs := make(chan os.Signal, 1)
    signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)

    fmt.Println("running, press Ctrl+C to stop")
    sig := <-sigs
    fmt.Println("\nreceived signal:", sig)
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`signal.NotifyContext` returns a context that is cancelled when the signal arrives. Pass this context to your server or worker - they stop cleanly when cancelled.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "context"
    "fmt"
    "os/signal"
    "syscall"
    "time"
)

func runWorker(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            fmt.Println("worker shutting down:", ctx.Err())
            return
        case <-time.After(500 * time.Millisecond):
            fmt.Println("worker tick")
        }
    }
}

func main() {
    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer stop()

    go runWorker(ctx)

    <-ctx.Done()
    fmt.Println("signal received, waiting for worker")
    time.Sleep(200 * time.Millisecond)
    fmt.Println("shutdown complete")
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Handle SIGTERM for graceful shutdown in containerised services -- Kubernetes sends SIGTERM before SIGKILL and waits `terminationGracePeriodSeconds` (default 30 s) for the process to exit cleanly. If your server ignores SIGTERM and Kubernetes sends SIGKILL, in-flight requests are abruptly dropped. Use `signal.NotifyContext` to tie a context to SIGTERM receipt, then pass that context to `http.Server.Shutdown` so it waits for in-flight requests to complete before closing. Always call `stop()` (the function returned by `signal.NotifyContext`) when you are done -- it releases the signal notification resources and re-enables the default signal behaviour so a second Ctrl+C terminates the process immediately rather than hanging. For multi-signal flows (first signal = drain, second signal = force exit), use `signal.Notify` with a buffered channel and handle the two signals separately in a select. Never call `signal.Notify` with an unbuffered channel in production -- if the goroutine is not ready to receive when the signal arrives, the delivery is skipped entirely.
</InProduction>


signal.NotifyContext ties a context to SIGINT/SIGTERM - cancel it to propagate graceful shutdown to every goroutine that respects context cancellation.

Signals


`os.Exit` terminates the process immediately with the given exit code. Deferred functions are not run. Exit code 0 means success; any non-zero value signals failure. Shell scripts, CI/CD pipelines, and orchestrators all inspect the exit code.

<ExamplePair>
<ExampleProse>

`os.Exit` exits immediately -- no deferred functions, no finalizers. Use it at program boundaries where there is nothing to clean up, not in the middle of a call stack.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "os"
)

func main() {
    args := os.Args[1:]
    if len(args) == 0 {
        fmt.Fprintln(os.Stderr, "usage: program <name>")
        os.Exit(1)
    }
    fmt.Println("hello,", args[0])
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The idiomatic Go pattern is a `run()` function that returns an error. `main` calls `run`, prints any error to stderr, and exits with code 1. Deferred functions inside `run` execute normally because `os.Exit` is only called from `main`.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "errors"
    "fmt"
    "os"
)

func run() error {
    args := os.Args[1:]
    if len(args) == 0 {
        return errors.New("usage: program <name>")
    }
    fmt.Println("hello,", args[0])
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`log.Fatal` logs the message then calls `os.Exit(1)`. It is a shorthand for startup failures where structured error handling is not yet set up.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "log"
    "net/http"
)

func main() {
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("ok"))
    })

    // log.Fatal calls os.Exit(1) after logging -- deferred functions do not run.
    log.Fatal(http.ListenAndServe(":8080", nil))
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Prefer the `run() error` pattern over calling `os.Exit` directly from inside your business logic -- this keeps deferred cleanup (closing files, flushing buffers, draining queues) working correctly because `os.Exit` skips all deferred functions when called anywhere in the call stack. `log.Fatal` is acceptable for startup failures (`log.Fatal("failed to connect to db:", err)`) where there is nothing to clean up yet, but it is wrong everywhere else in a running server -- use structured error returns and let the top-level handler decide whether to exit. Use non-zero exit codes consistently and document them: `0` = success, `1` = general error, `2` = misuse of shell builtins (by convention). CI/CD systems, `make`, and shell scripts all check exit codes; a process that always exits 0 even on failure silently swallows errors in pipelines. To inspect the exit code of a subprocess, use `errors.As(err, &exitErr)` on the error from `cmd.Wait()` and call `exitErr.ExitCode()`.
</InProduction>


Prefer returning an error from main over os.Exit so deferred cleanup runs -- use non-zero exit codes consistently because CI/CD pipelines and shell scripts rely on them.

Exit


`syscall.Exec` (or `golang.org/x/sys/unix.Exec` on Unix) replaces the running process with a new executable. Unlike `exec.Command`, there is no child process - the current process image is overwritten. On success it never returns.

<ExamplePair>
<ExampleProse>

`exec.LookPath` resolves a binary name to a full path using `$PATH`, which `syscall.Exec` requires. Pass the full argument list as the second argument - by convention `args[0]` is the binary name.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "os"
    "os/exec"
    "syscall"
)

func main() {
    binary, err := exec.LookPath("ls")
    if err != nil {
        fmt.Println("could not find ls:", err)
        os.Exit(1)
    }

    args := []string{"ls", "-la", "/tmp"}
    env := os.Environ()

    // This call does not return on success.
    if err := syscall.Exec(binary, args, env); err != nil {
        fmt.Println("exec failed:", err)
        os.Exit(1)
    }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A common use case: a launcher or supervisor that re-execs itself after downloading an updated binary. Run any cleanup before calling `Exec` - deferred functions will not run.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "os"
    "os/exec"
    "syscall"
)

func reexec(newBinary string) error {
    path, err := exec.LookPath(newBinary)
    if err != nil {
        return fmt.Errorf("look path: %w", err)
    }
    return syscall.Exec(path, os.Args, os.Environ())
}

func main() {
    // Perform any cleanup before re-exec; defer won't run after Exec.
    fmt.Println("handing off to updated binary")
    if err := reexec("/usr/local/bin/myapp-new"); err != nil {
        fmt.Println("re-exec failed:", err)
        os.Exit(1)
    }
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
`syscall.Exec` is for process-replacing wrappers - supervisors that re-exec on config reload, entrypoints that hand off to a different binary after initial setup, or shims that wrap another program. It does not return on success: any deferred functions, goroutines, and open file descriptors (other than those explicitly inherited) are lost. Do not use it as a substitute for `exec.Command` when you just want to run a subprocess and wait for it. On Linux the process keeps its PID, which is useful for PID-file-based process managers. Always flush logs and close non-inherited resources before calling `Exec` - there is no cleanup window after it succeeds. On non-Unix systems (Windows), `syscall.Exec` is not available; use `exec.Command` + `os.Exit` as an approximation, accepting that the process image is not replaced in place.
</InProduction>


syscall.Exec (or unix.Exec) replaces the current process image entirely - deferred functions never run, so use it only when you intentionally want to hand off to another binary.