base-4.18.1.0: Basic libraries

Copyright | (c) The University of Glasgow 2001
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | provisional
Portability | portable
Safe Haskell | Trustworthy
Language | Haskell2010

System.IO.Error

Contents

- I/O errors
  - Classifying I/O errors
  - Attributes of I/O errors
- Types of I/O error
  - `IOErrorType` predicates
- Throwing and catching I/O errors

Description

Standard IO Errors.

Synopsis

- type IOError = IOException
- userError :: String -> IOError
- mkIOError :: IOErrorType -> String -> Maybe Handle -> Maybe FilePath -> IOError
- annotateIOError :: IOError -> String -> Maybe Handle -> Maybe FilePath -> IOError
- isAlreadyExistsError :: IOError -> Bool
- isDoesNotExistError :: IOError -> Bool
- isAlreadyInUseError :: IOError -> Bool
- isFullError :: IOError -> Bool
- isEOFError :: IOError -> Bool
- isIllegalOperation :: IOError -> Bool
- isPermissionError :: IOError -> Bool
- isUserError :: IOError -> Bool
- isResourceVanishedError :: IOError -> Bool
- ioeGetErrorType :: IOError -> IOErrorType
- ioeGetLocation :: IOError -> String
- ioeGetErrorString :: IOError -> String
- ioeGetHandle :: IOError -> Maybe Handle
- ioeGetFileName :: IOError -> Maybe FilePath
- ioeSetErrorType :: IOError -> IOErrorType -> IOError
- ioeSetErrorString :: IOError -> String -> IOError
- ioeSetLocation :: IOError -> String -> IOError
- ioeSetHandle :: IOError -> Handle -> IOError
- ioeSetFileName :: IOError -> FilePath -> IOError
- data IOErrorType
- alreadyExistsErrorType :: IOErrorType
- doesNotExistErrorType :: IOErrorType
- alreadyInUseErrorType :: IOErrorType
- fullErrorType :: IOErrorType
- eofErrorType :: IOErrorType
- illegalOperationErrorType :: IOErrorType
- permissionErrorType :: IOErrorType
- userErrorType :: IOErrorType
- resourceVanishedErrorType :: IOErrorType
- isAlreadyExistsErrorType :: IOErrorType -> Bool
- isDoesNotExistErrorType :: IOErrorType -> Bool
- isAlreadyInUseErrorType :: IOErrorType -> Bool
- isFullErrorType :: IOErrorType -> Bool
- isEOFErrorType :: IOErrorType -> Bool
- isIllegalOperationErrorType :: IOErrorType -> Bool
- isPermissionErrorType :: IOErrorType -> Bool
- isUserErrorType :: IOErrorType -> Bool
- isResourceVanishedErrorType :: IOErrorType -> Bool
- ioError :: IOError -> IO a
- catchIOError :: IO a -> (IOError -> IO a) -> IO a
- tryIOError :: IO a -> IO (Either IOError a)
- modifyIOError :: (IOError -> IOError) -> IO a -> IO a

# I/O errors

type IOError = IOException Source #

The Haskell 2010 type for exceptions in the `IO` monad. Any I/O operation may raise an `IOException` instead of returning a result. For a more general type of exception, including also those that arise in pure code, see `Exception`.

In Haskell 2010, this is an opaque type.

userError :: String -> IOError Source #

Construct an `IOException` value with a string describing the error. The `fail` method of the `IO` instance of the `Monad` class raises a `userError`, thus:

    instance Monad IO where
      ...
      fail s = ioError (userError s)

mkIOError :: IOErrorType -> String -> Maybe Handle -> Maybe FilePath -> IOError Source #

Construct an `IOException` of the given type where the second argument describes the error location and the third and fourth argument contain the file handle and file path of the file involved in the error if applicable.

annotateIOError :: IOError -> String -> Maybe Handle -> Maybe FilePath -> IOError Source #

Adds a location description and maybe a file path and file handle to an `IOException`. If any of the file handle or file path is not given the corresponding value in the `IOException` remains unaltered.

## Classifying I/O errors

isAlreadyExistsError :: IOError -> Bool Source #

An error indicating that an `IO` operation failed because one of its arguments already exists.

isDoesNotExistError :: IOError -> Bool Source #

An error indicating that an `IO` operation failed because one of its arguments does not exist.

isAlreadyInUseError :: IOError -> Bool Source #

An error indicating that an `IO` operation failed because one of its arguments is a single-use resource, which is already being used (for example, opening the same file twice for writing might give this error).

isFullError :: IOError -> Bool Source #

An error indicating that an `IO` operation failed because the device is full.

isEOFError :: IOError -> Bool Source #

An error indicating that an `IO` operation failed because the end of file has been reached.

isIllegalOperation :: IOError -> Bool Source #

An error indicating that an `IO` operation failed because the operation was not possible. Any computation which returns an `IO` result may fail with `isIllegalOperation`. In some cases, an implementation will not be able to distinguish between the possible error causes. In this case it should fail with `isIllegalOperation`.

isPermissionError :: IOError -> Bool Source #

An error indicating that an `IO` operation failed because the user does not have sufficient operating system privilege to perform that operation.

isUserError :: IOError -> Bool Source #

A programmer-defined error value constructed using `userError`.

isResourceVanishedError :: IOError -> Bool Source #

An error indicating that the operation failed because the resource vanished. See `resourceVanishedErrorType`.

Since: base-4.14.0.0

## Attributes of I/O errors

ioeGetErrorType :: IOError -> IOErrorType Source #

ioeGetLocation :: IOError -> String Source #

ioeGetErrorString :: IOError -> String Source #

ioeGetHandle :: IOError -> Maybe Handle Source #

ioeGetFileName :: IOError -> Maybe FilePath Source #

ioeSetErrorType :: IOError -> IOErrorType -> IOError Source #

ioeSetErrorString :: IOError -> String -> IOError Source #

ioeSetLocation :: IOError -> String -> IOError Source #

ioeSetHandle :: IOError -> Handle -> IOError Source #

ioeSetFileName :: IOError -> FilePath -> IOError Source #

# Types of I/O error

data IOErrorType Source #

An abstract type that contains a value for each variant of `IOException`.

#### Instances

Instances details

Show IOErrorType Source # | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods showsPrec :: Int -> IOErrorType -> ShowS Source # show :: IOErrorType -> String Source # showList :: [IOErrorType] -> ShowS Source #
Eq IOErrorType Source # | Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods (==) :: IOErrorType -> IOErrorType -> Bool Source # (/=) :: IOErrorType -> IOErrorType -> Bool Source #

alreadyExistsErrorType :: IOErrorType Source #

I/O error where the operation failed because one of its arguments already exists.

doesNotExistErrorType :: IOErrorType Source #

I/O error where the operation failed because one of its arguments does not exist.

alreadyInUseErrorType :: IOErrorType Source #

I/O error where the operation failed because one of its arguments is a single-use resource, which is already being used.

fullErrorType :: IOErrorType Source #

I/O error where the operation failed because the device is full.

eofErrorType :: IOErrorType Source #

I/O error where the operation failed because the end of file has been reached.

illegalOperationErrorType :: IOErrorType Source #

I/O error where the operation is not possible.

permissionErrorType :: IOErrorType Source #

I/O error where the operation failed because the user does not have sufficient operating system privilege to perform that operation.

userErrorType :: IOErrorType Source #

I/O error that is programmer-defined.

resourceVanishedErrorType :: IOErrorType Source #

I/O error where the operation failed because the resource vanished. This happens when, for example, attempting to write to a closed socket or attempting to write to a named pipe that was deleted.

Since: base-4.14.0.0

## `IOErrorType` predicates

isAlreadyExistsErrorType :: IOErrorType -> Bool Source #

I/O error where the operation failed because one of its arguments already exists.

isDoesNotExistErrorType :: IOErrorType -> Bool Source #

I/O error where the operation failed because one of its arguments does not exist.

isAlreadyInUseErrorType :: IOErrorType -> Bool Source #

I/O error where the operation failed because one of its arguments is a single-use resource, which is already being used.

isFullErrorType :: IOErrorType -> Bool Source #

I/O error where the operation failed because the device is full.

isEOFErrorType :: IOErrorType -> Bool Source #

I/O error where the operation failed because the end of file has been reached.

isIllegalOperationErrorType :: IOErrorType -> Bool Source #

I/O error where the operation is not possible.

isPermissionErrorType :: IOErrorType -> Bool Source #

I/O error where the operation failed because the user does not have sufficient operating system privilege to perform that operation.

isUserErrorType :: IOErrorType -> Bool Source #

I/O error that is programmer-defined.

isResourceVanishedErrorType :: IOErrorType -> Bool Source #

I/O error where the operation failed because the resource vanished. See `resourceVanishedErrorType`.

Since: base-4.14.0.0

# Throwing and catching I/O errors

ioError :: IOError -> IO a Source #

Raise an `IOException` in the `IO` monad.

catchIOError :: IO a -> (IOError -> IO a) -> IO a Source #

The `catchIOError` function establishes a handler that receives any `IOException` raised in the action protected by `catchIOError`. An `IOException` is caught by the most recent handler established by one of the exception handling functions. These handlers are not selective: all `IOException`s are caught. Exception propagation must be explicitly provided in a handler by re-raising any unwanted exceptions. For example, in

    f = catchIOError g (\e -> if IO.isEOFError e then return [] else ioError e)

the function `f` returns `[]` when an end-of-file exception (cf. `isEOFError`) occurs in `g`; otherwise, the exception is propagated to the next outer handler.

When an exception propagates outside the main program, the Haskell system prints the associated `IOException` value and exits the program.

Non-I/O exceptions are not caught by this variant; to catch all exceptions, use `catch` from Control.Exception.

Since: base-4.4.0.0

tryIOError :: IO a -> IO (Either IOError a) Source #

The construct `tryIOError` `comp` exposes IO errors which occur within a computation, and which are not fully handled.

Non-I/O exceptions are not caught by this variant; to catch all exceptions, use `try` from Control.Exception.

Since: base-4.4.0.0

modifyIOError :: (IOError -> IOError) -> IO a -> IO a Source #

Catch any `IOException` that occurs in the computation and throw a modified version.