System.Posix.Terminal

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 | Safe
Language | Haskell2010

System.Posix.Terminal

Contents

- Terminal support
  - Terminal attributes
  - Terminal operations
  - Process groups
  - Testing a file descriptor
  - Pseudoterminal operations

Description

POSIX Terminal support

Synopsis

- data TerminalAttributes
- getTerminalAttributes :: Fd -> IO TerminalAttributes
- data TerminalState
  - = Immediately
  - | WhenDrained
  - | WhenFlushed
- setTerminalAttributes :: Fd -> TerminalAttributes -> TerminalState -> IO ()
- data TerminalMode
  - = InterruptOnBreak
  - | MapCRtoLF
  - | IgnoreBreak
  - | IgnoreCR
  - | IgnoreParityErrors
  - | MapLFtoCR
  - | CheckParity
  - | StripHighBit
  - | RestartOnAny
  - | StartStopInput
  - | StartStopOutput
  - | MarkParityErrors
  - | ProcessOutput
  - | MapLFtoCRLF
  - | OutputMapCRtoLF
  - | NoCRAtColumnZero
  - | ReturnMeansLF
  - | TabDelayMask0
  - | TabDelayMask3
  - | LocalMode
  - | ReadEnable
  - | TwoStopBits
  - | HangupOnClose
  - | EnableParity
  - | OddParity
  - | EnableEcho
  - | EchoErase
  - | EchoKill
  - | EchoLF
  - | ProcessInput
  - | ExtendedFunctions
  - | KeyboardInterrupts
  - | NoFlushOnInterrupt
  - | BackgroundWriteInterrupt
- withoutMode :: TerminalAttributes -> TerminalMode -> TerminalAttributes
- withMode :: TerminalAttributes -> TerminalMode -> TerminalAttributes
- terminalMode :: TerminalMode -> TerminalAttributes -> Bool
- bitsPerByte :: TerminalAttributes -> Int
- withBits :: TerminalAttributes -> Int -> TerminalAttributes
- data ControlCharacter
  - = EndOfFile
  - | EndOfLine
  - | Erase
  - | Interrupt
  - | Kill
  - | Quit
  - | Start
  - | Stop
  - | Suspend
- controlChar :: TerminalAttributes -> ControlCharacter -> Maybe Char
- withCC :: TerminalAttributes -> (ControlCharacter, Char) -> TerminalAttributes
- withoutCC :: TerminalAttributes -> ControlCharacter -> TerminalAttributes
- inputTime :: TerminalAttributes -> Int
- withTime :: TerminalAttributes -> Int -> TerminalAttributes
- minInput :: TerminalAttributes -> Int
- withMinInput :: TerminalAttributes -> Int -> TerminalAttributes
- newtype BaudRate where
  - BaudRate CSpeed
  - pattern B0 :: BaudRate
  - pattern B50 :: BaudRate
  - pattern B75 :: BaudRate
  - pattern B110 :: BaudRate
  - pattern B134 :: BaudRate
  - pattern B150 :: BaudRate
  - pattern B200 :: BaudRate
  - pattern B300 :: BaudRate
  - pattern B600 :: BaudRate
  - pattern B1200 :: BaudRate
  - pattern B1800 :: BaudRate
  - pattern B2400 :: BaudRate
  - pattern B4800 :: BaudRate
  - pattern B9600 :: BaudRate
  - pattern B19200 :: BaudRate
  - pattern B38400 :: BaudRate
  - pattern B57600 :: BaudRate
  - pattern B115200 :: BaudRate
  - pattern B230400 :: BaudRate
  - pattern B460800 :: BaudRate
  - pattern B500000 :: BaudRate
  - pattern B576000 :: BaudRate
  - pattern B921600 :: BaudRate
  - pattern B1000000 :: BaudRate
  - pattern B1152000 :: BaudRate
  - pattern B1500000 :: BaudRate
  - pattern B2000000 :: BaudRate
  - pattern B2500000 :: BaudRate
  - pattern B3000000 :: BaudRate
  - pattern B3500000 :: BaudRate
  - pattern B4000000 :: BaudRate
- inputSpeed :: TerminalAttributes -> BaudRate
- withInputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
- outputSpeed :: TerminalAttributes -> BaudRate
- withOutputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
- sendBreak :: Fd -> Int -> IO ()
- drainOutput :: Fd -> IO ()
- data QueueSelector
  - = InputQueue
  - | OutputQueue
  - | BothQueues
- discardData :: Fd -> QueueSelector -> IO ()
- data FlowAction
  - = SuspendOutput
  - | RestartOutput
  - | TransmitStop
  - | TransmitStart
- controlFlow :: Fd -> FlowAction -> IO ()
- getTerminalProcessGroupID :: Fd -> IO ProcessGroupID
- setTerminalProcessGroupID :: Fd -> ProcessGroupID -> IO ()
- queryTerminal :: Fd -> IO Bool
- getTerminalName :: Fd -> IO FilePath
- getControllingTerminalName :: IO FilePath
- openPseudoTerminal :: IO (Fd, Fd)
- getSlaveTerminalName :: Fd -> IO FilePath

# Terminal support

## Terminal attributes

data TerminalAttributes Source #

getTerminalAttributes :: Fd -> IO TerminalAttributes Source #

`getTerminalAttributes fd` calls `tcgetattr` to obtain the `TerminalAttributes` associated with `Fd` `fd`.

data TerminalState Source #

Constructors

Immediately |
WhenDrained |
WhenFlushed |

setTerminalAttributes :: Fd -> TerminalAttributes -> TerminalState -> IO () Source #

`setTerminalAttributes fd attr ts` calls `tcsetattr` to change the `TerminalAttributes` associated with `Fd` `fd` to `attr`, when the terminal is in the state indicated by `ts`.

data TerminalMode Source #

Constructors

InterruptOnBreak | `BRKINT` - Signal interrupt on break
MapCRtoLF | `ICRNL` - Map CR to NL on input
IgnoreBreak | `IGNBRK` - Ignore break condition
IgnoreCR | `IGNCR` - Ignore CR
IgnoreParityErrors | `IGNPAR` - Ignore characters with parity errors
MapLFtoCR | `INLCR` - Map NL to CR on input
CheckParity | `INPCK` - Enable input parity check
StripHighBit | `ISTRIP` - Strip character
RestartOnAny | `IXANY` - Enable any character to restart output
StartStopInput | `IXOFF` - Enable start/stop input control
StartStopOutput | `IXON` - Enable start/stop output control
MarkParityErrors | `PARMRK` - Mark parity errors
ProcessOutput | `OPOST` - Post-process output
MapLFtoCRLF | `ONLCR` - (XSI) Map NL to CR-NL on output Since: unix-2.8.0.0
OutputMapCRtoLF | `OCRNL` - (XSI) Map CR to NL on output Since: unix-2.8.0.0
NoCRAtColumnZero | `ONOCR` - (XSI) No CR output at column 0 Since: unix-2.8.0.0
ReturnMeansLF | `ONLRET` - (XSI) NL performs CR function Since: unix-2.8.0.0
TabDelayMask0 | `TABDLY(TAB0)` - (XSI) Select horizontal-tab delays: type 0 Since: unix-2.8.0.0
TabDelayMask3 | `TABDLY(TAB3)` - (XSI) Select horizontal-tab delays: type 3 Since: unix-2.8.0.0
LocalMode | `CLOCAL` - Ignore modem status lines
ReadEnable | `CREAD` - Enable receiver
TwoStopBits | `CSTOPB` - Send two stop bits, else one
HangupOnClose | `HUPCL` - Hang up on last close
EnableParity | `PARENB` - Parity enable
OddParity | `PARODD` - Odd parity, else even
EnableEcho | `ECHO` - Enable echo
EchoErase | `ECHOE` - Echo erase character as error-correcting backspace
EchoKill | `ECHOK` - Echo KILL
EchoLF | `ECHONL` - Echo NL
ProcessInput | `ICANON` - Canonical input (erase and kill processing)
ExtendedFunctions | `IEXTEN` - Enable extended input character processing
KeyboardInterrupts | `ISIG` - Enable signals
NoFlushOnInterrupt | `NOFLSH` - Disable flush after interrupt or quit
BackgroundWriteInterrupt | `TOSTOP` - Send `SIGTTOU` for background output

withoutMode :: TerminalAttributes -> TerminalMode -> TerminalAttributes Source #

withMode :: TerminalAttributes -> TerminalMode -> TerminalAttributes Source #

terminalMode :: TerminalMode -> TerminalAttributes -> Bool Source #

bitsPerByte :: TerminalAttributes -> Int Source #

withBits :: TerminalAttributes -> Int -> TerminalAttributes Source #

data ControlCharacter Source #

Constructors

EndOfFile |
EndOfLine |
Erase |
Interrupt |
Kill |
Quit |
Start |
Stop |
Suspend |

controlChar :: TerminalAttributes -> ControlCharacter -> Maybe Char Source #

withCC :: TerminalAttributes -> (ControlCharacter, Char) -> TerminalAttributes Source #

withoutCC :: TerminalAttributes -> ControlCharacter -> TerminalAttributes Source #

inputTime :: TerminalAttributes -> Int Source #

withTime :: TerminalAttributes -> Int -> TerminalAttributes Source #

minInput :: TerminalAttributes -> Int Source #

withMinInput :: TerminalAttributes -> Int -> TerminalAttributes Source #

newtype BaudRate Source #

Serial line baudrate. The set of supported speeds is system-dependent. Portable use of the provided pattern synonyms that are outside the list mandated by POSIX requires `#ifdef` guards.

Applications may need to be prepared to encounter speeds not known at compile time, these can be handled generically via the `BaudRate` constructor. In other words, the provided pattern synonyms are not necessarily a `COMPLETE` set.

All non-zero pseudo-terminal baud rates are functionally equivalent, and the `pty` driver may accept any speed within a suitable range. Requested speeds may be rounded up or down to fit into the supported range.

Constructors

BaudRate CSpeed |

Bundled Patterns

pattern B0 :: BaudRate | Hang up
pattern B50 :: BaudRate | 50 baud
pattern B75 :: BaudRate | 75 baud
pattern B110 :: BaudRate | 110 baud
pattern B134 :: BaudRate | 5 baud
pattern B150 :: BaudRate | 150 baud
pattern B200 :: BaudRate | 200 baud
pattern B300 :: BaudRate | 300 baud
pattern B600 :: BaudRate | 600 baud
pattern B1200 :: BaudRate | 1200 baud
pattern B1800 :: BaudRate | 1800 baud
pattern B2400 :: BaudRate | 2400 baud
pattern B4800 :: BaudRate | 4800 baud
pattern B9600 :: BaudRate | 9600 baud
pattern B19200 :: BaudRate | 19200 baud
pattern B38400 :: BaudRate | 38400 baud
pattern B57600 :: BaudRate | 57600 baud, non-POSIX system-dependent extension
pattern B115200 :: BaudRate | 115200 baud, non-POSIX system-dependent extension
pattern B230400 :: BaudRate | 230400 baud, non-POSIX system-dependent extension
pattern B460800 :: BaudRate | 460800 baud, non-POSIX system-dependent extension
pattern B500000 :: BaudRate | 500000 baud, non-POSIX system-dependent extension
pattern B576000 :: BaudRate | 576000 baud, non-POSIX system-dependent extension
pattern B921600 :: BaudRate | 921600 baud, non-POSIX system-dependent extension
pattern B1000000 :: BaudRate | 1000000 baud, non-POSIX system-dependent extension
pattern B1152000 :: BaudRate | 1152000 baud, non-POSIX system-dependent extension
pattern B1500000 :: BaudRate | 1500000 baud, non-POSIX system-dependent extension
pattern B2000000 :: BaudRate | 2000000 baud, non-POSIX system-dependent extension
pattern B2500000 :: BaudRate | 2500000 baud, non-POSIX system-dependent extension
pattern B3000000 :: BaudRate | 3000000 baud, non-POSIX system-dependent extension
pattern B3500000 :: BaudRate | 3500000 baud, non-POSIX system-dependent extension
pattern B4000000 :: BaudRate | 4000000 baud, non-POSIX system-dependent extension

#### Instances

Instances details

Enum BaudRate Source # |
Instance details Defined in System.Posix.Terminal.Common Methods succ :: BaudRate -> BaudRate # pred :: BaudRate -> BaudRate # toEnum :: Int -> BaudRate # fromEnum :: BaudRate -> Int # enumFrom :: BaudRate -> [BaudRate] # enumFromThen :: BaudRate -> BaudRate -> [BaudRate] # enumFromTo :: BaudRate -> BaudRate -> [BaudRate] # enumFromThenTo :: BaudRate -> BaudRate -> BaudRate -> [BaudRate] #
Num BaudRate Source # |
Instance details Defined in System.Posix.Terminal.Common Methods (+) :: BaudRate -> BaudRate -> BaudRate # (-) :: BaudRate -> BaudRate -> BaudRate # (*) :: BaudRate -> BaudRate -> BaudRate # negate :: BaudRate -> BaudRate # abs :: BaudRate -> BaudRate # signum :: BaudRate -> BaudRate # fromInteger :: Integer -> BaudRate #
Real BaudRate Source # |
Instance details Defined in System.Posix.Terminal.Common Methods toRational :: BaudRate -> Rational #
Show BaudRate Source # |
Instance details Defined in System.Posix.Terminal.Common Methods showsPrec :: Int -> BaudRate -> ShowS # show :: BaudRate -> String # showList :: [BaudRate] -> ShowS #
Eq BaudRate Source # |
Instance details Defined in System.Posix.Terminal.Common Methods (==) :: BaudRate -> BaudRate -> Bool # (/=) :: BaudRate -> BaudRate -> Bool #
Ord BaudRate Source # |
Instance details Defined in System.Posix.Terminal.Common Methods compare :: BaudRate -> BaudRate -> Ordering # (<) :: BaudRate -> BaudRate -> Bool # (<=) :: BaudRate -> BaudRate -> Bool # (>) :: BaudRate -> BaudRate -> Bool # (>=) :: BaudRate -> BaudRate -> Bool # max :: BaudRate -> BaudRate -> BaudRate # min :: BaudRate -> BaudRate -> BaudRate #

inputSpeed :: TerminalAttributes -> BaudRate Source #

withInputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes Source #

outputSpeed :: TerminalAttributes -> BaudRate Source #

withOutputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes Source #

## Terminal operations

sendBreak :: Fd -> Int -> IO () Source #

`sendBreak fd duration` calls `tcsendbreak` to transmit a continuous stream of zero-valued bits on `Fd` `fd` for the specified implementation-dependent `duration`.

drainOutput :: Fd -> IO () Source #

`drainOutput fd` calls `tcdrain` to block until all output written to `Fd` `fd` has been transmitted.

Throws `IOError` ("unsupported operation") if platform does not provide `tcdrain(3)` (use `#if HAVE_TCDRAIN` CPP guard to detect availability).

data QueueSelector Source #

Constructors

InputQueue |
OutputQueue |
BothQueues |

discardData :: Fd -> QueueSelector -> IO () Source #

`discardData fd queues` calls `tcflush` to discard pending input and/or output for `Fd` `fd`, as indicated by the `QueueSelector` `queues`.

data FlowAction Source #

Constructors

SuspendOutput | TCOOFF
RestartOutput | TCOON
TransmitStop | TCIOFF
TransmitStart | TCION

controlFlow :: Fd -> FlowAction -> IO () Source #

`controlFlow fd action` calls `tcflow` to control the flow of data on `Fd` `fd`, as indicated by `action`.

## Process groups

getTerminalProcessGroupID :: Fd -> IO ProcessGroupID Source #

`getTerminalProcessGroupID fd` calls `tcgetpgrp` to obtain the `ProcessGroupID` of the foreground process group associated with the terminal attached to `Fd` `fd`.

setTerminalProcessGroupID :: Fd -> ProcessGroupID -> IO () Source #

`setTerminalProcessGroupID fd pgid` calls `tcsetpgrp` to set the `ProcessGroupID` of the foreground process group associated with the terminal attached to `Fd` `fd` to `pgid`.

## Testing a file descriptor

queryTerminal :: Fd -> IO Bool Source #

`queryTerminal fd` calls `isatty` to determine whether or not `Fd` `fd` is associated with a terminal.

getTerminalName :: Fd -> IO FilePath Source #

`getTerminalName fd` calls `ttyname` to obtain a name associated with the terminal for `Fd` `fd`. If `fd` is associated with a terminal, `getTerminalName` returns the name of the terminal.

getControllingTerminalName :: IO FilePath Source #

`getControllingTerminalName` calls `ctermid` to obtain a name associated with the controlling terminal for the process. If a controlling terminal exists, `getControllingTerminalName` returns the name of the controlling terminal.

Throws `IOError` ("unsupported operation") if platform does not provide `ctermid(3)` (use `#if HAVE_CTERMID` CPP guard to detect availability).

## Pseudoterminal operations

openPseudoTerminal :: IO (Fd, Fd) Source #

`openPseudoTerminal` creates a pseudoterminal (pty) pair, and returns the newly created pair as a (`master`, `slave`) tuple.

getSlaveTerminalName :: Fd -> IO FilePath Source #

`getSlaveTerminalName` calls `ptsname` to obtain the name of the slave terminal associated with a pseudoterminal pair. The file descriptor to pass in must be that of the master.