base-4.18.1.0: Basic libraries

Copyright | (c) The University of Glasgow 1994-2008
License | see libraries/base/LICENSE
Maintainer | libraries@haskell.org
Stability | internal
Portability | non-portable
Safe Haskell | Trustworthy
Language | Haskell2010

GHC.IO.Handle.FD

Description

Handle operations implemented by file descriptors (FDs)

Synopsis

- stdin :: Handle
- stdout :: Handle
- stderr :: Handle
- openFile :: FilePath -> IOMode -> IO Handle
- withFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
- openBinaryFile :: FilePath -> IOMode -> IO Handle
- withBinaryFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
- openFileBlocking :: FilePath -> IOMode -> IO Handle
- withFileBlocking :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
- mkHandleFromFD :: FD -> IODeviceType -> FilePath -> IOMode -> Bool -> Maybe TextEncoding -> IO Handle
- fdToHandle :: FD -> IO Handle
- fdToHandle' :: CInt -> Maybe IODeviceType -> Bool -> FilePath -> IOMode -> Bool -> IO Handle
- handleToFd :: Handle -> IO FD

# Documentation

stdin :: Handle Source #

A handle managing input from the Haskell program's standard input channel.

stdout :: Handle Source #

A handle managing output to the Haskell program's standard output channel.

stderr :: Handle Source #

A handle managing output to the Haskell program's standard error channel.

openFile :: FilePath -> IOMode -> IO Handle Source #

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 (on POSIX systems) is a FIFO without a reader and `WriteMode` was requested; or
- `isPermissionError` if the user does not have permission to open the file.

On POSIX systems, `openFile` is an interruptible operation as described in Control.Exception.

Note: if you will be working with files containing binary data, you'll want to be using `openBinaryFile`.

withFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r Source #

``withFile` name mode act` opens a file like `openFile` and passes the resulting handle to the computation `act`. The handle will be closed on exit from `withFile`, whether by normal termination or by raising an exception. If closing the handle raises an exception, then this exception will be raised by `withFile` rather than any exception raised by `act`.

openBinaryFile :: FilePath -> IOMode -> IO Handle Source #

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

withBinaryFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r Source #

A version of `openBinaryFile` that takes an action to perform with the handle. If an exception occurs in the action, then the file will be closed automatically. The action should close the file when finished with it so the file does not remain open until the garbage collector collects the handle.

openFileBlocking :: FilePath -> IOMode -> IO Handle Source #

Like `openFile`, but opens the file in ordinary blocking mode. This can be useful for opening a FIFO for writing: if we open in non-blocking mode then the open will fail if there are no readers, whereas a blocking open will block until a reader appear.

Note: when blocking happens, an OS thread becomes tied up with the processing, so the program must have at least another OS thread if it wants to unblock itself. By corollary, a non-threaded runtime will need a process-external trigger in order to become unblocked.

On POSIX systems, `openFileBlocking` is an interruptible operation as described in Control.Exception.

Since: base-4.4.0.0

withFileBlocking :: FilePath -> IOMode -> (Handle -> IO r) -> IO r Source #

``withFileBlocking` name mode act` opens a file like `openFileBlocking` and passes the resulting handle to the computation `act`. The handle will be closed on exit from `withFileBlocking`, whether by normal termination or by raising an exception. If closing the handle raises an exception, then this exception will be raised by `withFile` rather than any exception raised by `act`.

mkHandleFromFD :: FD -> IODeviceType -> FilePath -> IOMode -> Bool -> Maybe TextEncoding -> IO Handle Source #

fdToHandle :: FD -> IO Handle Source #

Turn an existing file descriptor into a Handle. This is used by various external libraries to make Handles.

Makes a binary Handle. This is for historical reasons; it should probably be a text Handle with the default encoding and newline translation instead.

fdToHandle' :: CInt -> Maybe IODeviceType -> Bool -> FilePath -> IOMode -> Bool -> IO Handle Source #

Old API kept to avoid breaking clients

handleToFd :: Handle -> IO FD Source #

Turn an existing Handle into a file descriptor. This function throws an IOError if the Handle does not reference a file descriptor.