std / os/signal

os/signal

import "std:os/signal"

Provides POSIX signal handling using a polling model. Register handlers, ignore or reset signals, and poll for pending signals from your main loop.

View source on Codeberg →

Index

Types Error Constants Signal Constants Platform-Specific Signals Notify Ignore Reset Poll Pending Raise Kill Name

Types

# 
type Signal int

Signal represents a signal number.

# 
type Error int

Error represents a signal operation error.

# 
type Handler func(Signal, any)

Handler is a callback function for signal handling. The first argument is the signal, the second is optional user context.

Error Constants

# 
const (
    OK         Error = iota
    ErrInvalid
    ErrNoMem
    ErrPerm
    ErrNoProc
)

Error constants for signal operations. OK indicates success. ErrInvalid indicates an invalid signal number. ErrNoMem indicates out of memory or no handler slots. ErrPerm indicates the operation is not permitted. ErrNoProc indicates no such process.

Signal Constants

# 
const (
    SIGHUP  Signal = 1   /* Hangup */
    SIGINT  Signal = 2   /* Interrupt (Ctrl+C) */
    SIGQUIT Signal = 3   /* Quit */
    SIGILL  Signal = 4   /* Illegal instruction */
    SIGABRT Signal = 6   /* Abort */
    SIGFPE  Signal = 8   /* Floating-point exception */
    SIGKILL Signal = 9   /* Kill (cannot be caught) */
    SIGSEGV Signal = 11  /* Segmentation fault */
    SIGPIPE Signal = 13  /* Broken pipe */
    SIGALRM Signal = 14  /* Alarm clock */
    SIGTERM Signal = 15  /* Termination */
)

Portable POSIX signal constants with consistent values across Linux, macOS, and BSD.

Platform-Specific Signals

# 
func SIGUSR1() Signal

Returns the platform-specific signal number for SIGUSR1.

# 
func SIGUSR2() Signal

Returns the platform-specific signal number for SIGUSR2.

# 
func SIGCHLD() Signal

Returns the platform-specific signal number for SIGCHLD.

# 
func SIGCONT() Signal

Returns the platform-specific signal number for SIGCONT.

# 
func SIGSTOP() Signal

Returns the platform-specific signal number for SIGSTOP.

# 
func SIGTSTP() Signal

Returns the platform-specific signal number for SIGTSTP.

Handler Registration

# 
func Notify(handler Handler, ctx any, signals ...Signal) Error

Registers a handler to be called when any of the given signals arrive. The handler will be called from Poll with the signal and context. Only one handler per signal is supported; new registrations replace existing ones. Returns OK on success, ErrInvalid for invalid signal, ErrPerm if signal cannot be caught.

# 
func Ignore(signals ...Signal) Error

Causes the given signals to be ignored. Removes any registered handlers for these signals. Returns OK on success, ErrInvalid for invalid signal, ErrPerm if signal cannot be ignored.

# 
func Reset(signals ...Signal) Error

Restores the default behavior for the given signals. Removes any registered handlers for these signals. Returns OK on success, ErrInvalid for invalid signal.

Polling

# 
func Poll() int

Checks for pending signals and dispatches to registered handlers. Returns the number of signals that were processed. This should be called regularly from your main loop.

# 
func Pending() bool

Returns true if any signals are waiting to be processed.

Sending Signals

# 
func Raise(sig Signal) Error

Sends a signal to the current process. Returns OK on success, ErrInvalid for invalid signal.

# 
func Kill(pid int, sig Signal) Error

Sends a signal to a process. Returns OK on success, ErrInvalid for invalid signal, ErrNoProc for invalid pid, ErrPerm if not permitted.

Utilities

# 
func Name(sig Signal) string

Returns the name of a signal as a string (e.g. "SIGINT", "SIGTERM"). Returns "unknown" for unrecognized signals.