Module System.IO

Author

Michael Hanus, Bernd Brassel

Version

October 2025

Library for IO operations like reading and writing files that are not already contained in the prelude.

Exported Datatypes:

Handle IOMode SeekMode

Data types for dealing with files

data Handle

The abstract type of a handle for a stream.

Known instances:

Eq Handle

data IOMode

The modes for opening a file.

Constructors:

ReadMode :: IOMode
WriteMode :: IOMode
AppendMode :: IOMode

data SeekMode

The modes for positioning with hSeek in a file.

Constructors:

AbsoluteSeek :: SeekMode
RelativeSeek :: SeekMode
SeekFromEnd :: SeekMode

Standard input/output handles

stdin :: Handle

Standard input stream.

Further infos:

externally defined

stdout :: Handle

Standard output stream.

Further infos:

externally defined

stderr :: Handle

Standard error stream.

Further infos:

externally defined

Opening and closing files

openFile :: String -> IOMode -> IO Handle

Opens a file in specified mode and returns a handle to it.

hClose :: Handle -> IO ()

Closes a file handle and flushes the buffer in case of output file.

withFile :: String -> IOMode -> (Handle -> IO a) -> IO a

The computation withFile path mode action opens the file specified path in the given mode and runs action on the obtained file handle before closing the file. The file will be also closed when the action raises an exception. Therefore, withFile avoids open file handles in contrast to

openFile path mode >>= (\h -> action h >>= hClose h)

For instance, reading the complete contents of a file and closing it can be done by

withFile "FILENAME" ReadMode hGetContents

`:: FilePath`	The path to the file that should be opened
`-> IOMode`	The mode in which the file should be opened
`-> Handle -> IO a`	The action to run with the obtained handle
`-> IO a`

hFlush :: Handle -> IO ()

Flushes the buffer associated to handle in case of output file.

hIsEOF :: Handle -> IO Bool

Is handle at end of file?

isEOF :: IO Bool

Is standard input at end of file?

Operation on handles

hSeek :: Handle -> SeekMode -> Int -> IO ()

Set the position of a handle to a seekable stream (e.g., a file). If the second argument is AbsoluteSeek, SeekFromEnd, or RelativeSeek, the position is set relative to the beginning of the file, to the end of the file, or to the current position, respectively.

hWaitForInput :: Handle -> Int -> IO Bool

Waits until input is available on the given handle. If no input is available within t milliseconds, it returns False, otherwise it returns True.

`:: Handle`	a handle for an input stream
`-> Int`	milliseconds to wait for input (< 0 : no time out)
`-> IO Bool`

hWaitForInputs :: [Handle] -> Int -> IO Int

Waits until input is available on some of the given handles. If no input is available within the given milliseconds, it returns -1, otherwise it returns the index of the corresponding handle with the available data.

`:: [Handle]`	a list of handles for input streams
`-> Int`	milliseconds to wait for input (< 0 : no time out)
`-> IO Int`	`-1` if no input is available within the time out, otherwise `i` if `(handles!!i)` has data available

hReady :: Handle -> IO Bool

Checks whether an input is available on a given handle.

hGetChar :: Handle -> IO Char

Reads a character from an input handle and returns it. Throws an error if the end of file has been reached.

hGetLine :: Handle -> IO String

Reads a line from an input handle and returns it. Throws an error if the end of file has been reached while reading the first character. If the end of file is reached later in the line, it ist treated as a line terminator and the (partial) line is returned.

hGetContents :: Handle -> IO String

Reads the complete contents from an input handle and closes the input handle before returning the contents.

getContents :: IO String

Reads the complete contents from the standard input stream until EOF.

hPutChar :: Handle -> Char -> IO ()

Puts a character to an output handle.

hPutStr :: Handle -> String -> IO ()

Puts a string to an output handle.

hPutStrLn :: Handle -> String -> IO ()

Puts a string with a newline to an output handle.

hPrint :: Show a => Handle -> a -> IO ()

Converts a term into a string and puts it to an output handle.

Properties of handles

hIsReadable :: Handle -> IO Bool

Is the handle readable?

hIsWritable :: Handle -> IO Bool

Is the handle writable?

hIsTerminalDevice :: Handle -> IO Bool

Is the handle connected to a terminal?