posix-pty-0.2.2: Pseudo terminal interaction with subprocesses.

Copyright | (C) 2013 Merijn Verstraaten
License | BSD-style (see the file LICENSE)
Maintainer | Merijn Verstraaten <merijn@inconsistent.nl>
Stability | experimental
Portability | haha
Safe Haskell | Trustworthy
Language | Haskell2010

System.Posix.Pty

Contents

- Subprocess Creation
- Data Structures
- Pty Interaction Functions
- Blocking on `Pty`s
- Re-exports of System.Posix.Terminal

Description

A module for interacting with subprocesses through a pseudo terminal (pty). Provides functions for reading from, writing to and resizing pseudo terminals. Re-exports most of System.Posix.Terminal, providing wrappers that work with the `Pty` type where necessary.

Synopsis

- spawnWithPty :: Maybe [(String, String)] -> Bool -> FilePath -> [String] -> (Int, Int) -> IO (Pty, ProcessHandle)
- data Pty
- data PtyControlCode
  - = FlushRead
  - | FlushWrite
  - | OutputStopped
  - | OutputStarted
  - | DoStop
  - | NoStop
- createPty :: Fd -> IO (Maybe Pty)
- closePty :: Pty -> IO ()
- tryReadPty :: Pty -> IO (Either [PtyControlCode] ByteString)
- readPty :: Pty -> IO ByteString
- writePty :: Pty -> ByteString -> IO ()
- resizePty :: Pty -> (Int, Int) -> IO ()
- ptyDimensions :: Pty -> IO (Int, Int)
- threadWaitReadPty :: Pty -> IO ()
- threadWaitWritePty :: Pty -> IO ()
- threadWaitReadPtySTM :: Pty -> IO (STM (), IO ())
- threadWaitWritePtySTM :: Pty -> IO (STM (), IO ())
- getTerminalAttributes :: Pty -> IO TerminalAttributes
- setTerminalAttributes :: Pty -> TerminalAttributes -> TerminalState -> IO ()
- sendBreak :: Pty -> Int -> IO ()
- drainOutput :: Pty -> IO ()
- discardData :: Pty -> QueueSelector -> IO ()
- controlFlow :: Pty -> FlowAction -> IO ()
- getTerminalProcessGroupID :: Pty -> IO ProcessGroupID
- getTerminalName :: Pty -> IO FilePath
- getSlaveTerminalName :: Pty -> IO FilePath
- data FlowAction
  - = SuspendOutput
  - | RestartOutput
  - | TransmitStop
  - | TransmitStart
- data QueueSelector
  - = InputQueue
  - | OutputQueue
  - | BothQueues
- data TerminalState
  - = Immediately
  - | WhenDrained
  - | WhenFlushed
- newtype BaudRate where
  - BaudRate CSpeed
  - pattern B4000000 :: BaudRate
  - pattern B3500000 :: BaudRate
  - pattern B3000000 :: BaudRate
  - pattern B2500000 :: BaudRate
  - pattern B2000000 :: BaudRate
  - pattern B1500000 :: BaudRate
  - pattern B1152000 :: BaudRate
  - pattern B1000000 :: BaudRate
  - pattern B921600 :: BaudRate
  - pattern B576000 :: BaudRate
  - pattern B500000 :: BaudRate
  - pattern B460800 :: BaudRate
  - pattern B230400 :: BaudRate
  - pattern B115200 :: BaudRate
  - pattern B76800 :: BaudRate
  - pattern B57600 :: BaudRate
  - pattern B28800 :: BaudRate
  - pattern B14400 :: BaudRate
  - pattern B7200 :: BaudRate
  - pattern B38400 :: BaudRate
  - pattern B19200 :: BaudRate
  - pattern B9600 :: BaudRate
  - pattern B4800 :: BaudRate
  - pattern B2400 :: BaudRate
  - pattern B1800 :: BaudRate
  - pattern B1200 :: BaudRate
  - pattern B600 :: BaudRate
  - pattern B300 :: BaudRate
  - pattern B200 :: BaudRate
  - pattern B150 :: BaudRate
  - pattern B134 :: BaudRate
  - pattern B110 :: BaudRate
  - pattern B75 :: BaudRate
  - pattern B50 :: BaudRate
  - pattern B0 :: BaudRate
- data ControlCharacter
  - = EndOfFile
  - | EndOfLine
  - | Erase
  - | Interrupt
  - | Kill
  - | Quit
  - | Start
  - | Stop
  - | Suspend
- 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
- data TerminalAttributes
- withoutMode :: TerminalAttributes -> TerminalMode -> TerminalAttributes
- withMode :: TerminalAttributes -> TerminalMode -> TerminalAttributes
- terminalMode :: TerminalMode -> TerminalAttributes -> Bool
- bitsPerByte :: TerminalAttributes -> Int
- withBits :: TerminalAttributes -> Int -> TerminalAttributes
- 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
- inputSpeed :: TerminalAttributes -> BaudRate
- withInputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
- outputSpeed :: TerminalAttributes -> BaudRate
- withOutputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
- getControllingTerminalName :: IO FilePath

# Subprocess Creation

spawnWithPty Source #

Arguments

:: Maybe [(String, String)] | Optional environment for the new process.
-> Bool | Search for the executable in PATH?
-> FilePath | Program's name.
-> [String] | Command line arguments for the program.
-> (Int, Int) | Initial dimensions for the pseudo terminal.
-> IO (Pty, ProcessHandle) |

Create a new process that is connected to the current process through a pseudo terminal. If an environment is specified, then only the specified environment variables will be set. If no environment is specified the process will inherit its environment from the current process. Example:

    pty <- spawnWithPty (Just [("SHELL", "tcsh")]) True "ls" ["-l"] (20, 10)

This searches the user's PATH for a binary called `ls`, then runs this binary with the commandline argument `-l` in a terminal that is 20 characters wide and 10 characters high. The environment of `ls` will contains one variable, SHELL, which will be set to the value "tcsh".

# Data Structures

data Pty Source #

Abstract pseudo terminal type.

data PtyControlCode Source #

Pseudo terminal control information.

Terminal read queue
  The terminal read queue contains the data that was written from the master terminal to the slave terminal, which was not read from the slave yet.
Terminal write queue
  The terminal write queue contains the data that was written from the slave terminal, which was not sent to the master yet.

Constructors

FlushRead | Terminal read queue was flushed.
FlushWrite | Terminal write queue was flushed.
OutputStopped | Terminal output was stopped.
OutputStarted | Terminal output was restarted.
DoStop | Terminal stop and start characters are `^S` and `^Q` respectively.
NoStop | Terminal stop and start characters are NOT `^S` and `^Q`.

#### Instances

Instances details

Read PtyControlCode Source # |
Instance details Defined in System.Posix.Pty Methods readsPrec :: Int -> ReadS PtyControlCode Source # readList :: ReadS [PtyControlCode] Source # readPrec :: ReadPrec PtyControlCode Source # readListPrec :: ReadPrec [PtyControlCode] Source #
Show PtyControlCode Source # |
Instance details Defined in System.Posix.Pty Methods showsPrec :: Int -> PtyControlCode -> ShowS Source # show :: PtyControlCode -> String Source # showList :: [PtyControlCode] -> ShowS Source #
Eq PtyControlCode Source # |
Instance details Defined in System.Posix.Pty Methods (==) :: PtyControlCode -> PtyControlCode -> Bool Source # (/=) :: PtyControlCode -> PtyControlCode -> Bool Source #

# Pty Interaction Functions

createPty :: Fd -> IO (Maybe Pty) Source #

Produces a `Pty` if the file descriptor is associated with a terminal and Nothing if not.

closePty :: Pty -> IO () Source #

Close this pseudo terminal.

tryReadPty :: Pty -> IO (Either [PtyControlCode] ByteString) Source #

Attempt to read data from a pseudo terminal. Produces either the data read or a list of `PtyControlCode` `s` indicating which control status events that have happened on the slave terminal.

Throws an `IOError` of type `eofErrorType` when the terminal has been closed, for example when the subprocess has terminated.

readPty :: Pty -> IO ByteString Source #

The same as `tryReadPty`, but discards any control status events.

writePty :: Pty -> ByteString -> IO () Source #

Write a `ByteString` to the pseudo terminal, throws an `IOError` when the terminal has been closed, for example when the subprocess has terminated.

resizePty :: Pty -> (Int, Int) -> IO () Source #

Set the pseudo terminal's dimensions to the specified width and height.

ptyDimensions :: Pty -> IO (Int, Int) Source #

Produces the pseudo terminal's current dimensions.

# Blocking on `Pty`s

threadWaitReadPty :: Pty -> IO () Source #

Equivalent to `threadWaitRead`.

threadWaitWritePty :: Pty -> IO () Source #

Equivalent to `threadWaitWrite`.

threadWaitReadPtySTM :: Pty -> IO (STM (), IO ()) Source #

Equivalent to `threadWaitReadSTM`.

threadWaitWritePtySTM :: Pty -> IO (STM (), IO ()) Source #

Equivalent to `threadWaitWriteSTM`.

# Re-exports of System.Posix.Terminal

This module re-exports the entirety of System.Posix.Terminal, with the exception of the following functions:

setTerminalProcessGroupID
  This function can't be used after a process using the slave terminal has been created, rendering it mostly useless for working with `Pty` `s` created by this module.
queryTerminal
  Useless, `Pty` is always a terminal.
openPseudoTerminal
  Only useful for the kind of tasks this module is supposed abstract away.

In addition, some functions from System.Posix.Terminal work directly with `Fd` `s`, these have been hidden and instead the following replacements working on `Pty` `s` are exported.

getTerminalAttributes :: Pty -> IO TerminalAttributes Source #

See `getTerminalAttributes`.

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

See `setTerminalAttributes`.

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

See `sendBreak`.

drainOutput :: Pty -> IO () Source #

See `drainOutput`.

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

See `discardData`.

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

See `controlFlow`.

getTerminalProcessGroupID :: Pty -> IO ProcessGroupID Source #

See `getTerminalProcessGroupID`.

getTerminalName :: Pty -> IO FilePath Source #

See `getTerminalName`.

getSlaveTerminalName :: Pty -> IO FilePath Source #

See `getSlaveTerminalName`.

data FlowAction Source #

Constructors

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

data QueueSelector Source #

Constructors

InputQueue |
OutputQueue |
BothQueues |

data TerminalState Source #

Constructors

Immediately |
WhenDrained |
WhenFlushed |

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 B4000000 :: BaudRate | 4000000 baud, non-POSIX system-dependent extension
pattern B3500000 :: BaudRate | 3500000 baud, non-POSIX system-dependent extension
pattern B3000000 :: BaudRate | 3000000 baud, non-POSIX system-dependent extension
pattern B2500000 :: BaudRate | 2500000 baud, non-POSIX system-dependent extension
pattern B2000000 :: BaudRate | 2000000 baud, non-POSIX system-dependent extension
pattern B1500000 :: BaudRate | 1500000 baud, non-POSIX system-dependent extension
pattern B1152000 :: BaudRate | 1152000 baud, non-POSIX system-dependent extension
pattern B1000000 :: BaudRate | 1000000 baud, non-POSIX system-dependent extension
pattern B921600 :: BaudRate | 921600 baud, non-POSIX system-dependent extension
pattern B576000 :: BaudRate | 576000 baud, non-POSIX system-dependent extension
pattern B500000 :: BaudRate | 500000 baud, non-POSIX system-dependent extension
pattern B460800 :: BaudRate | 460800 baud, non-POSIX system-dependent extension
pattern B230400 :: BaudRate | 230400 baud, non-POSIX system-dependent extension
pattern B115200 :: BaudRate | 115200 baud, non-POSIX system-dependent extension
pattern B76800 :: BaudRate | 76800 baud, non-POSIX system-dependent extension
pattern B57600 :: BaudRate | 57600 baud, non-POSIX system-dependent extension
pattern B28800 :: BaudRate | 28800 baud, non-POSIX system-dependent extension
pattern B14400 :: BaudRate | 14400 baud, non-POSIX system-dependent extension
pattern B7200 :: BaudRate | 7200 baud, non-POSIX system-dependent extension
pattern B38400 :: BaudRate | 38400 baud
pattern B19200 :: BaudRate | 19200 baud
pattern B9600 :: BaudRate | 9600 baud
pattern B4800 :: BaudRate | 4800 baud
pattern B2400 :: BaudRate | 2400 baud
pattern B1800 :: BaudRate | 1800 baud
pattern B1200 :: BaudRate | 1200 baud
pattern B600 :: BaudRate | 600 baud
pattern B300 :: BaudRate | 300 baud
pattern B200 :: BaudRate | 200 baud
pattern B150 :: BaudRate | 150 baud

pattern B134 :: BaudRate

1. 5 baud

pattern B110 :: BaudRate | 110 baud
pattern B75 :: BaudRate | 75 baud
pattern B50 :: BaudRate | 50 baud
pattern B0 :: BaudRate | Hang up

#### Instances

Instances details

Enum BaudRate |

Instance details

Defined in System.Posix.Terminal.Common

Methods

succ :: BaudRate -> BaudRate Source #

pred :: BaudRate -> BaudRate Source #

toEnum :: Int -> BaudRate Source #

fromEnum :: BaudRate -> Int Source #

enumFrom :: BaudRate -> [BaudRate] Source #

enumFromThen :: BaudRate -> BaudRate -> [BaudRate] Source #

enumFromTo :: BaudRate -> BaudRate -> [BaudRate] Source #

enumFromThenTo :: BaudRate -> BaudRate -> BaudRate -> [BaudRate] Source #

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

data ControlCharacter Source #

Constructors

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

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

data TerminalAttributes Source #

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

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

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

bitsPerByte :: TerminalAttributes -> Int Source #

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

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 #

inputSpeed :: TerminalAttributes -> BaudRate Source #

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

outputSpeed :: TerminalAttributes -> BaudRate Source #

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

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).