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.

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.

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.

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.

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

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.

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.