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 Ptys
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 B57600 :: 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 PtyControlCodes 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 Ptys 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 Fds, these have been hidden and instead the following replacements working on Ptys 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 B57600 :: BaudRate	57600 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	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).

Subprocess Creation

Data Structures

Instances

Pty Interaction Functions

Blocking on Ptys

Re-exports of System.Posix.Terminal

Instances

Blocking on `Pty`s