System.Posix.Signals

unix-2.8.5.1: POSIX functionality

Copyright | (c) The University of Glasgow 2002
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | provisional
Portability | non-portable (requires POSIX)
Safe Haskell | Trustworthy
Language | Haskell2010

System.Posix.Signals

Contents

- The Signal type
- Specific signals
- Sending signals
- Handling signals
- Signal sets
- The process signal mask
- The alarm timer
- Waiting for signals
- The `NOCLDSTOP` flag

Description

POSIX signal support

Synopsis

- type Signal = CInt
- nullSignal :: Signal
- internalAbort :: Signal
- sigABRT :: CInt
- realTimeAlarm :: Signal
- sigALRM :: CInt
- busError :: Signal
- sigBUS :: CInt
- processStatusChanged :: Signal
- sigCHLD :: CInt
- continueProcess :: Signal
- sigCONT :: CInt
- floatingPointException :: Signal
- sigFPE :: CInt
- lostConnection :: Signal
- sigHUP :: CInt
- illegalInstruction :: Signal
- sigILL :: CInt
- keyboardSignal :: Signal
- sigINT :: CInt
- killProcess :: Signal
- sigKILL :: CInt
- openEndedPipe :: Signal
- sigPIPE :: CInt
- keyboardTermination :: Signal
- sigQUIT :: CInt
- segmentationViolation :: Signal
- sigSEGV :: CInt
- softwareStop :: Signal
- sigSTOP :: CInt
- softwareTermination :: Signal
- sigTERM :: CInt
- keyboardStop :: Signal
- sigTSTP :: CInt
- backgroundRead :: Signal
- sigTTIN :: CInt
- backgroundWrite :: Signal
- sigTTOU :: CInt
- userDefinedSignal1 :: Signal
- sigUSR1 :: CInt
- userDefinedSignal2 :: Signal
- sigUSR2 :: CInt
- pollableEvent :: Signal
- sigPOLL :: CInt
- profilingTimerExpired :: Signal
- sigPROF :: CInt
- badSystemCall :: Signal
- sigSYS :: CInt
- breakpointTrap :: Signal
- sigTRAP :: CInt
- urgentDataAvailable :: Signal
- sigURG :: CInt
- virtualTimerExpired :: Signal
- sigVTALRM :: CInt
- cpuTimeLimitExceeded :: Signal
- sigXCPU :: CInt
- fileSizeLimitExceeded :: Signal
- sigXFSZ :: CInt
- raiseSignal :: Signal -> IO ()
- signalProcess :: Signal -> ProcessID -> IO ()
- signalProcessGroup :: Signal -> ProcessGroupID -> IO ()
- data Handler
  - = Default
  - | Ignore
  - | Catch (IO ())
  - | CatchOnce (IO ())
  - | CatchInfo (SignalInfo -> IO ())
  - | CatchInfoOnce (SignalInfo -> IO ())
- data SignalInfo = SignalInfo {
  - siginfoSignal :: Signal
  - siginfoError :: Errno
  - siginfoSpecific :: SignalSpecificInfo
  }
- data SignalSpecificInfo
  - = NoSignalSpecificInfo
  - | SigChldInfo {
    - siginfoPid :: ProcessID
    - siginfoUid :: UserID
    - siginfoStatus :: ProcessStatus
    }
- installHandler :: Signal -> Handler -> Maybe SignalSet -> IO Handler
- data SignalSet
- emptySignalSet :: SignalSet
- fullSignalSet :: SignalSet
- reservedSignals :: SignalSet
- addSignal :: Signal -> SignalSet -> SignalSet
- deleteSignal :: Signal -> SignalSet -> SignalSet
- inSignalSet :: Signal -> SignalSet -> Bool
- getSignalMask :: IO SignalSet
- setSignalMask :: SignalSet -> IO ()
- blockSignals :: SignalSet -> IO ()
- unblockSignals :: SignalSet -> IO ()
- scheduleAlarm :: Int -> IO Int
- getPendingSignals :: IO SignalSet
- awaitSignal :: Maybe SignalSet -> IO ()
- setStoppedChildFlag :: Bool -> IO Bool
- queryStoppedChildFlag :: IO Bool

# The Signal type

type Signal = CInt Source #

# Specific signals

nullSignal :: Signal Source #

internalAbort :: Signal Source #

Alias for `sigABRT`.

sigABRT :: CInt Source #

Process abort signal.

realTimeAlarm :: Signal Source #

Alias for `sigALRM`.

sigALRM :: CInt Source #

Alarm clock.

busError :: Signal Source #

Alias for `sigBUS`.

sigBUS :: CInt Source #

Access to an undefined portion of a memory object.

processStatusChanged :: Signal Source #

Alias for `sigCHLD`.

sigCHLD :: CInt Source #

Child process terminated, stopped, or continued.

continueProcess :: Signal Source #

Alias for `sigCONT`.

sigCONT :: CInt Source #

Continue executing, if stopped.

floatingPointException :: Signal Source #

Alias for `sigFPE`.

sigFPE :: CInt Source #

Erroneous arithmetic operation.

lostConnection :: Signal Source #

Alias for `sigHUP`.

sigHUP :: CInt Source #

Hangup.

illegalInstruction :: Signal Source #

Alias for `sigILL`.

sigILL :: CInt Source #

Illegal instruction.

keyboardSignal :: Signal Source #

Alias for `sigINT`.

sigINT :: CInt Source #

Terminal interrupt signal.

killProcess :: Signal Source #

Alias for `sigKILL`.

sigKILL :: CInt Source #

Kill (cannot be caught or ignored).

openEndedPipe :: Signal Source #

Alias for `sigPIPE`.

sigPIPE :: CInt Source #

Write on a pipe with no one to read it.

keyboardTermination :: Signal Source #

Alias for `sigQUIT`.

sigQUIT :: CInt Source #

Terminal quit signal.

segmentationViolation :: Signal Source #

Alias for `sigSEGV`.

sigSEGV :: CInt Source #

Invalid memory reference.

softwareStop :: Signal Source #

Alias for `sigSTOP`.

sigSTOP :: CInt Source #

Stop executing (cannot be caught or ignored).

softwareTermination :: Signal Source #

Alias for `sigTERM`.

sigTERM :: CInt Source #

Termination signal.

keyboardStop :: Signal Source #

Alias for `sigTSTP`.

sigTSTP :: CInt Source #

Terminal stop signal.

backgroundRead :: Signal Source #

Alias for `sigTTIN`.

sigTTIN :: CInt Source #

Background process attempting read.

backgroundWrite :: Signal Source #

Alias for `sigTTOU`.

sigTTOU :: CInt Source #

Background process attempting write.

userDefinedSignal1 :: Signal Source #

Alias for `sigUSR1`.

sigUSR1 :: CInt Source #

User-defined signal 1.

userDefinedSignal2 :: Signal Source #

Alias for `sigUSR2`.

sigUSR2 :: CInt Source #

User-defined signal 2.

pollableEvent :: Signal Source #

Alias for `sigPOLL`.

sigPOLL :: CInt Source #

Pollable event.

profilingTimerExpired :: Signal Source #

Alias for `sigPROF`.

sigPROF :: CInt Source #

Profiling timer expired.

badSystemCall :: Signal Source #

Alias for `sigSYS`.

sigSYS :: CInt Source #

Bad system call.

breakpointTrap :: Signal Source #

Alias for `sigTRAP`.

sigTRAP :: CInt Source #

Trace/breakpoint trap.

urgentDataAvailable :: Signal Source #

Alias for `sigURG`.

sigURG :: CInt Source #

High bandwidth data is available at a socket.

virtualTimerExpired :: Signal Source #

Alias for `sigVTALRM`.

sigVTALRM :: CInt Source #

Virtual timer expired.

cpuTimeLimitExceeded :: Signal Source #

Alias for `sigXCPU`.

sigXCPU :: CInt Source #

CPU time limit exceeded.

fileSizeLimitExceeded :: Signal Source #

Alias for `sigXFSZ`.

sigXFSZ :: CInt Source #

File size limit exceeded.

# Sending signals

raiseSignal :: Signal -> IO () Source #

`raiseSignal int` calls `kill` to signal the current process with interrupt signal `int`.

signalProcess :: Signal -> ProcessID -> IO () Source #

`signalProcess int pid` calls `kill` to signal process `pid` with interrupt signal `int`.

signalProcessGroup :: Signal -> ProcessGroupID -> IO () Source #

`signalProcessGroup int pgid` calls `kill` to signal all processes in group `pgid` with interrupt signal `int`.

# Handling signals

data Handler Source #

The actions to perform when a signal is received.

Constructors

Default | Sets the disposition of the signal to `SIG_DFL`, which means we want the default action associated with the signal. For example, the default action for `SIGTERM` (and various other signals) is to terminate the process.
Ignore | Set the disposition of the signal to `SIG_IGN`, which means we want to ignore the signal. Ignored signals will not be delivered to the process, and if also blocked will not be added to the pending set for later delivery (if/when unblocked). Some signals (e.g. `SIGSTOP` and `SIGKILL`) cannot be caught or ignored. not yet: | Hold
Catch (IO ()) | signal handler is not reset
CatchOnce (IO ()) | signal handler is automatically reset (via `SA_RESETHAND`)
CatchInfo (SignalInfo -> IO ()) | Since: unix-2.7.0.0
CatchInfoOnce (SignalInfo -> IO ()) | Since: unix-2.7.0.0

data SignalInfo Source #

Information about a received signal (derived from `siginfo_t`).

Since: unix-2.7.0.0

Constructors

SignalInfo |
Fields siginfoSignal :: Signal siginfoError :: Errno siginfoSpecific :: SignalSpecificInfo

data SignalSpecificInfo Source #

Information specific to a particular type of signal (derived from `siginfo_t`).

Since: unix-2.7.0.0

Constructors

NoSignalSpecificInfo |
SigChldInfo |
Fields siginfoPid :: ProcessID siginfoUid :: UserID siginfoStatus :: ProcessStatus

installHandler Source #

Arguments

:: Signal |
-> Handler |
-> Maybe SignalSet | other signals to block
-> IO Handler | old handler

`installHandler int handler iset` calls `sigaction` to install an interrupt handler for signal `int`. If `handler` is `Default`, `SIG_DFL` is installed; if `handler` is `Ignore`, `SIG_IGN` is installed; if `handler` is `Catch action`, a handler is installed which will invoke `action` in a new thread when (or shortly after) the signal is received. If `iset` is `Just s`, then the `sa_mask` of the `sigaction` structure is set to `s`; otherwise it is cleared. The previously installed signal handler for `int` is returned

# Signal sets

data SignalSet Source #

emptySignalSet :: SignalSet Source #

fullSignalSet :: SignalSet Source #

reservedSignals :: SignalSet Source #

A set of signals reserved for use by the implementation. In GHC, this will normally include either `sigVTALRM` or `sigALRM`.

addSignal :: Signal -> SignalSet -> SignalSet infixr 9 Source #

deleteSignal :: Signal -> SignalSet -> SignalSet infixr 9 Source #

inSignalSet :: Signal -> SignalSet -> Bool Source #

# The process signal mask

getSignalMask :: IO SignalSet Source #

`getSignalMask` calls `sigprocmask` to determine the set of interrupts which are currently being blocked.

setSignalMask :: SignalSet -> IO () Source #

`setSignalMask mask` calls `sigprocmask` with `SIG_SETMASK` to block all interrupts in `mask`.

blockSignals :: SignalSet -> IO () Source #

`blockSignals mask` calls `sigprocmask` with `SIG_BLOCK` to add all interrupts in `mask` to the set of blocked interrupts.

unblockSignals :: SignalSet -> IO () Source #

`unblockSignals mask` calls `sigprocmask` with `SIG_UNBLOCK` to remove all interrupts in `mask` from the set of blocked interrupts.

# The alarm timer

scheduleAlarm :: Int -> IO Int Source #

`scheduleAlarm i` calls `alarm` to schedule a real time alarm at least `i` seconds in the future.

# Waiting for signals

getPendingSignals :: IO SignalSet Source #

`getPendingSignals` calls `sigpending` to obtain the set of interrupts which have been received but are currently blocked.

awaitSignal :: Maybe SignalSet -> IO () Source #

`awaitSignal iset` suspends execution until an interrupt is received. If `iset` is `Just s`, `awaitSignal` calls `sigsuspend`, installing `s` as the new signal mask before suspending execution; otherwise, it calls `sigsuspend` with current signal mask. Note that RTS scheduler signal (either `virtualTimerExpired` or `realTimeAlarm`) could cause premature termination of this call. It might be necessary to block that signal before invocation of `awaitSignal` with `blockSignals` `reservedSignals`.

`awaitSignal` returns when signal was received and processed by a signal handler, or if the signal could not be caught. If you have installed any signal handlers with `installHandler`, it may be wise to call `yield` directly after `awaitSignal` to ensure that the signal handler runs as promptly as possible.

# The `NOCLDSTOP` flag

setStoppedChildFlag :: Bool -> IO Bool Source #

Tells the system whether or not to set the `SA_NOCLDSTOP` flag when installing new signal handlers.

queryStoppedChildFlag :: IO Bool Source #

Queries the current state of the stopped child flag.