Haskell Hierarchical Libraries (base package)ContentsIndex
GHC.Handle
Portability non-portable
Stability internal
Maintainer libraries@haskell.org
Description
This module defines the basic operations on I/O "handles".
Synopsis
withHandle :: String -> Handle -> (Handle__ -> IO (Handle__, a)) -> IO a
withHandle' :: String -> Handle -> MVar Handle__ -> (Handle__ -> IO (Handle__, a)) -> IO a
withHandle_ :: String -> Handle -> (Handle__ -> IO a) -> IO a
wantWritableHandle :: String -> Handle -> (Handle__ -> IO a) -> IO a
wantReadableHandle :: String -> Handle -> (Handle__ -> IO a) -> IO a
wantSeekableHandle :: String -> Handle -> (Handle__ -> IO a) -> IO a
newEmptyBuffer :: RawBuffer -> BufferState -> Int -> Buffer
allocateBuffer :: Int -> BufferState -> IO Buffer
readCharFromBuffer :: RawBuffer -> Int -> IO (Char, Int)
writeCharIntoBuffer :: RawBuffer -> Int -> Char -> IO Int
flushWriteBufferOnly :: Handle__ -> IO ()
flushWriteBuffer :: FD -> Bool -> Buffer -> IO Buffer
flushReadBuffer :: FD -> Buffer -> IO Buffer
fillReadBuffer :: FD -> Bool -> Bool -> Buffer -> IO Buffer
readRawBuffer :: String -> FD -> Bool -> RawBuffer -> Int -> CInt -> IO CInt
readRawBufferPtr :: String -> FD -> Bool -> Ptr CChar -> Int -> CInt -> IO CInt
writeRawBuffer :: String -> FD -> Bool -> RawBuffer -> Int -> CInt -> IO CInt
writeRawBufferPtr :: String -> FD -> Bool -> Ptr CChar -> Int -> CInt -> IO CInt
unlockFile :: CInt -> IO CInt
write_off :: CInt -> Bool -> Ptr CChar -> Int -> CInt -> IO CInt
write_rawBuffer :: CInt -> Bool -> RawBuffer -> Int -> CInt -> IO CInt
read_off :: FD -> Bool -> Ptr CChar -> Int -> CInt -> IO CInt
read_rawBuffer :: FD -> Bool -> RawBuffer -> Int -> CInt -> IO CInt
ioe_closedHandle :: IO a
ioe_EOF :: IO a
ioe_notReadable :: IO a
ioe_notWritable :: IO a
stdin :: Handle
stdout :: Handle
stderr :: Handle
data IOMode
= ReadMode
| WriteMode
| AppendMode
| ReadWriteMode
openFile :: FilePath -> IOMode -> IO Handle
openBinaryFile :: FilePath -> IOMode -> IO Handle
openFd :: FD -> Maybe FDType -> FilePath -> IOMode -> Bool -> Bool -> IO Handle
fdToHandle :: FD -> IO Handle
hFileSize :: Handle -> IO Integer
hIsEOF :: Handle -> IO Bool
isEOF :: IO Bool
hLookAhead :: Handle -> IO Char
hSetBuffering :: Handle -> BufferMode -> IO ()
hSetBinaryMode :: Handle -> Bool -> IO ()
hFlush :: Handle -> IO ()
hDuplicate :: Handle -> IO Handle
hDuplicateTo :: Handle -> Handle -> IO ()
hClose :: Handle -> IO ()
hClose_help :: Handle__ -> IO Handle__
type HandlePosition = Integer
data HandlePosn = HandlePosn Handle HandlePosition
hGetPosn :: Handle -> IO HandlePosn
hSetPosn :: HandlePosn -> IO ()
data SeekMode
= AbsoluteSeek
| RelativeSeek
| SeekFromEnd
hSeek :: Handle -> SeekMode -> Integer -> IO ()
hTell :: Handle -> IO Integer
hIsOpen :: Handle -> IO Bool
hIsClosed :: Handle -> IO Bool
hIsReadable :: Handle -> IO Bool
hIsWritable :: Handle -> IO Bool
hGetBuffering :: Handle -> IO BufferMode
hIsSeekable :: Handle -> IO Bool
hSetEcho :: Handle -> Bool -> IO ()
hGetEcho :: Handle -> IO Bool
hIsTerminalDevice :: Handle -> IO Bool
hShow :: Handle -> IO String
Documentation
withHandle :: String -> Handle -> (Handle__ -> IO (Handle__, a)) -> IO a
withHandle' :: String -> Handle -> MVar Handle__ -> (Handle__ -> IO (Handle__, a)) -> IO a
withHandle_ :: String -> Handle -> (Handle__ -> IO a) -> IO a
wantWritableHandle :: String -> Handle -> (Handle__ -> IO a) -> IO a
wantReadableHandle :: String -> Handle -> (Handle__ -> IO a) -> IO a
wantSeekableHandle :: String -> Handle -> (Handle__ -> IO a) -> IO a
newEmptyBuffer :: RawBuffer -> BufferState -> Int -> Buffer
allocateBuffer :: Int -> BufferState -> IO Buffer
readCharFromBuffer :: RawBuffer -> Int -> IO (Char, Int)
writeCharIntoBuffer :: RawBuffer -> Int -> Char -> IO Int
flushWriteBufferOnly :: Handle__ -> IO ()
flushWriteBuffer :: FD -> Bool -> Buffer -> IO Buffer
flushReadBuffer :: FD -> Buffer -> IO Buffer
fillReadBuffer :: FD -> Bool -> Bool -> Buffer -> IO Buffer
readRawBuffer :: String -> FD -> Bool -> RawBuffer -> Int -> CInt -> IO CInt
readRawBufferPtr :: String -> FD -> Bool -> Ptr CChar -> Int -> CInt -> IO CInt
writeRawBuffer :: String -> FD -> Bool -> RawBuffer -> Int -> CInt -> IO CInt
writeRawBufferPtr :: String -> FD -> Bool -> Ptr CChar -> Int -> CInt -> IO CInt
unlockFile :: CInt -> IO CInt
write_off :: CInt -> Bool -> Ptr CChar -> Int -> CInt -> IO CInt
write_rawBuffer :: CInt -> Bool -> RawBuffer -> Int -> CInt -> IO CInt
read_off :: FD -> Bool -> Ptr CChar -> Int -> CInt -> IO CInt
read_rawBuffer :: FD -> Bool -> RawBuffer -> Int -> CInt -> IO CInt
ioe_closedHandle :: IO a
ioe_EOF :: IO a
ioe_notReadable :: IO a
ioe_notWritable :: IO a
stdin :: Handle
A handle managing input from the Haskell program's standard input channel.
stdout :: Handle
A handle managing output to the Haskell program's standard output channel.
stderr :: Handle
A handle managing output to the Haskell program's standard error channel.
data IOMode
Constructors
ReadMode
WriteMode
AppendMode
ReadWriteMode
Instances
Eq IOMode
Ord IOMode
Ix IOMode
Enum IOMode
Read IOMode
Show IOMode
openFile :: FilePath -> IOMode -> IO Handle

Computation openFile file mode allocates and returns a new, open handle to manage the file file. It manages input if mode is ReadMode, output if mode is WriteMode or AppendMode, and both input and output if mode is ReadWriteMode.

If the file does not exist and it is opened for output, it should be created as a new file. If mode is WriteMode and the file already exists, then it should be truncated to zero length. Some operating systems delete empty files, so there is no guarantee that the file will exist following an openFile with mode WriteMode unless it is subsequently written to successfully. The handle is positioned at the end of the file if mode is AppendMode, and otherwise at the beginning (in which case its internal position is 0). The initial buffer mode is implementation-dependent.

This operation may fail with:

openBinaryFile :: FilePath -> IOMode -> IO Handle
Like openFile, but open the file in binary mode. On Windows, reading a file in text mode (which is the default) will translate CRLF to LF, and writing will translate LF to CRLF. This is usually what you want with text files. With binary files this is undesirable; also, as usual under Microsoft operating systems, text mode treats control-Z as EOF. Binary mode turns off all special treatment of end-of-line and end-of-file characters. (See also hSetBinaryMode.)
openFd :: FD -> Maybe FDType -> FilePath -> IOMode -> Bool -> Bool -> IO Handle
fdToHandle :: FD -> IO Handle
hFileSize :: Handle -> IO Integer
For a handle hdl which attached to a physical file, hFileSize hdl returns the size of that file in 8-bit bytes.
hIsEOF :: Handle -> IO Bool
For a readable handle hdl, hIsEOF hdl returns True if no further input can be taken from hdl or for a physical file, if the current I/O position is equal to the length of the file. Otherwise, it returns False.
isEOF :: IO Bool
The computation isEOF is identical to hIsEOF, except that it works only on stdin.
hLookAhead :: Handle -> IO Char

Computation hLookAhead returns the next character from the handle without removing it from the input buffer, blocking until a character is available.

This operation may fail with:

hSetBuffering :: Handle -> BufferMode -> IO ()

Computation hSetBuffering hdl mode sets the mode of buffering for handle hdl on subsequent reads and writes.

If the buffer mode is changed from BlockBuffering or LineBuffering to NoBuffering, then

  • if hdl is writable, the buffer is flushed as for hFlush;
  • if hdl is not writable, the contents of the buffer is discarded.

This operation may fail with:

  • isPermissionError if the handle has already been used for reading or writing and the implementation does not allow the buffering mode to be changed.
hSetBinaryMode :: Handle -> Bool -> IO ()
Select binary mode (True) or text mode (False) on a open handle. (GHC only; see also openBinaryFile.)
hFlush :: Handle -> IO ()

The action hFlush hdl causes any items buffered for output in handle hdl to be sent immediately to the operating system.

This operation may fail with:

  • isFullError if the device is full;
  • isPermissionError if a system resource limit would be exceeded. It is unspecified whether the characters in the buffer are discarded or retained under these circumstances.
hDuplicate :: Handle -> IO Handle
Returns a duplicate of the original handle, with its own buffer and file pointer. The original handle's buffer is flushed, including discarding any input data, before the handle is duplicated.
hDuplicateTo :: Handle -> Handle -> IO ()

Makes the second handle a duplicate of the first handle. The second handle will be closed first, if it is not already.

This can be used to retarget the standard Handles, for example:

 do h <- openFile "mystdout" WriteMode
    hDuplicateTo h stdout
hClose :: Handle -> IO ()
Computation hClose hdl makes handle hdl closed. Before the computation finishes, if hdl is writable its buffer is flushed as for hFlush. Performing hClose on a handle that has already been closed has no effect; doing so not an error. All other operations on a closed handle will fail. If hClose fails for any reason, any further operations (apart from hClose) on the handle will still fail as if hdl had been successfully closed.
hClose_help :: Handle__ -> IO Handle__
type HandlePosition = Integer
data HandlePosn
Constructors
HandlePosn Handle HandlePosition
Instances
Eq HandlePosn
Show HandlePosn
hGetPosn :: Handle -> IO HandlePosn
Computation hGetPosn hdl returns the current I/O position of hdl as a value of the abstract type HandlePosn.
hSetPosn :: HandlePosn -> IO ()

If a call to hGetPosn hdl returns a position p, then computation hSetPosn p sets the position of hdl to the position it held at the time of the call to hGetPosn.

This operation may fail with:

data SeekMode
A mode that determines the effect of hSeek hdl mode i, as follows:
Constructors
AbsoluteSeekthe position of hdl is set to i.
RelativeSeekthe position of hdl is set to offset i from the current position.
SeekFromEndthe position of hdl is set to offset i from the end of the file.
Instances
Eq SeekMode
Ord SeekMode
Ix SeekMode
Enum SeekMode
Read SeekMode
Show SeekMode
hSeek :: Handle -> SeekMode -> Integer -> IO ()

Computation hSeek hdl mode i sets the position of handle hdl depending on mode. The offset i is given in terms of 8-bit bytes.

If hdl is block- or line-buffered, then seeking to a position which is not in the current buffer will first cause any items in the output buffer to be written to the device, and then cause the input buffer to be discarded. Some handles may not be seekable (see hIsSeekable), or only support a subset of the possible positioning operations (for instance, it may only be possible to seek to the end of a tape, or to a positive offset from the beginning or current position). It is not possible to set a negative I/O position, or for a physical file, an I/O position beyond the current end-of-file.

This operation may fail with:

hTell :: Handle -> IO Integer
hIsOpen :: Handle -> IO Bool
hIsClosed :: Handle -> IO Bool
hIsReadable :: Handle -> IO Bool
hIsWritable :: Handle -> IO Bool
hGetBuffering :: Handle -> IO BufferMode
Computation hGetBuffering hdl returns the current buffering mode for hdl.
hIsSeekable :: Handle -> IO Bool
hSetEcho :: Handle -> Bool -> IO ()
Set the echoing status of a handle connected to a terminal (GHC only).
hGetEcho :: Handle -> IO Bool
Get the echoing status of a handle connected to a terminal (GHC only).
hIsTerminalDevice :: Handle -> IO Bool
Is the handle connected to a terminal? (GHC only)
hShow :: Handle -> IO String
hShow is in the IO monad, and gives more comprehensive output than the (pure) instance of Show for Handle.
Produced by Haddock version 0.6