| Haskell Hierarchical Libraries (base package) | Contents | Index

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:

- `isAlreadyInUseError` if the file is already open and cannot be reopened;
- `isDoesNotExistError` if the file does not exist; or
- `isPermissionError` if the user does not have permission to open the file.

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:

- `isEOFError` if the end of file has been reached.

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:

- `isPermissionError` if a system resource limit would be exceeded.

data SeekMode

A mode that determines the effect of `hSeek` `hdl mode i`, as follows:
Constructors

AbsoluteSeek | the position of `hdl` is set to `i`.
RelativeSeek | the position of `hdl` is set to offset `i` from the current position.
SeekFromEnd | the 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:

- `isPermissionError` if a system resource limit would be exceeded.

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