unix-2.7.1.0: 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
- 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

# Specific signals

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

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

# Sending signals

raiseSignal :: Signal -> IO ()

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

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

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

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

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

# Handling signals

data Handler

The actions to perform when a signal is received.

Constructors

Default |
Ignore |
Catch (IO ()) |
CatchOnce (IO ()) |
CatchInfo (SignalInfo -> IO ()) | Since: 2.7.0.0
CatchInfoOnce (SignalInfo -> IO ()) | Since: 2.7.0.0

data SignalInfo

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

Since: 2.7.0.0

Constructors

SignalInfo |

Fields

siginfoSignal :: Signal
siginfoError :: Errno
siginfoSpecific :: SignalSpecificInfo

data SignalSpecificInfo

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

Since: 2.7.0.0

Constructors

NoSignalSpecificInfo |
SigChldInfo |

Fields

siginfoPid :: ProcessID
siginfoUid :: UserID
siginfoStatus :: ProcessStatus

installHandler

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

emptySignalSet :: SignalSet

fullSignalSet :: SignalSet

reservedSignals :: SignalSet

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

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

inSignalSet :: Signal -> SignalSet -> Bool

# The process signal mask

getSignalMask :: IO SignalSet

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

setSignalMask :: SignalSet -> IO ()

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

blockSignals :: SignalSet -> IO ()

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

unblockSignals :: SignalSet -> IO ()

`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

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

# Waiting for signals

getPendingSignals :: IO SignalSet

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

awaitSignal :: Maybe SignalSet -> IO ()

`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

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

queryStoppedChildFlag :: IO Bool

Queries the current state of the stopped child flag.