posix-pty-0.2.2: Pseudo terminal interaction with subprocesses.
Copyright(C) 2013 Merijn Verstraaten
LicenseBSD-style (see the file LICENSE)
MaintainerMerijn Verstraaten <merijn@inconsistent.nl>
Stabilityexperimental
Portabilityhaha
Safe HaskellTrustworthy
LanguageHaskell2010

System.Posix.Pty

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

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.

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 Ptys

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

Equivalent to threadWaitReadSTM.

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.

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

getControllingTerminalName :: IO FilePath #

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