base-4.3.1.0: Basic libraries

Portability | portable
Stability | provisional
Maintainer | ffi@haskell.org

Foreign.C.Error

Contents

- Haskell representations of `errno` values
  - Common `errno` symbols
  - `Errno` functions
  - Guards for IO operations that may fail

Description

C-specific Marshalling support: Handling of C "errno" error codes.

Synopsis

- newtype Errno = Errno CInt
- eOK :: Errno
- e2BIG :: Errno
- eACCES :: Errno
- eADDRINUSE :: Errno
- eADDRNOTAVAIL :: Errno
- eADV :: Errno
- eAFNOSUPPORT :: Errno
- eAGAIN :: Errno
- eALREADY :: Errno
- eBADF :: Errno
- eBADMSG :: Errno
- eBADRPC :: Errno
- eBUSY :: Errno
- eCHILD :: Errno
- eCOMM :: Errno
- eCONNABORTED :: Errno
- eCONNREFUSED :: Errno
- eCONNRESET :: Errno
- eDEADLK :: Errno
- eDESTADDRREQ :: Errno
- eDIRTY :: Errno
- eDOM :: Errno
- eDQUOT :: Errno
- eEXIST :: Errno
- eFAULT :: Errno
- eFBIG :: Errno
- eFTYPE :: Errno
- eHOSTDOWN :: Errno
- eHOSTUNREACH :: Errno
- eIDRM :: Errno
- eILSEQ :: Errno
- eINPROGRESS :: Errno
- eINTR :: Errno
- eINVAL :: Errno
- eIO :: Errno
- eISCONN :: Errno
- eISDIR :: Errno
- eLOOP :: Errno
- eMFILE :: Errno
- eMLINK :: Errno
- eMSGSIZE :: Errno
- eMULTIHOP :: Errno
- eNAMETOOLONG :: Errno
- eNETDOWN :: Errno
- eNETRESET :: Errno
- eNETUNREACH :: Errno
- eNFILE :: Errno
- eNOBUFS :: Errno
- eNODATA :: Errno
- eNODEV :: Errno
- eNOENT :: Errno
- eNOEXEC :: Errno
- eNOLCK :: Errno
- eNOLINK :: Errno
- eNOMEM :: Errno
- eNOMSG :: Errno
- eNONET :: Errno
- eNOPROTOOPT :: Errno
- eNOSPC :: Errno
- eNOSR :: Errno
- eNOSTR :: Errno
- eNOSYS :: Errno
- eNOTBLK :: Errno
- eNOTCONN :: Errno
- eNOTDIR :: Errno
- eNOTEMPTY :: Errno
- eNOTSOCK :: Errno
- eNOTTY :: Errno
- eNXIO :: Errno
- eOPNOTSUPP :: Errno
- ePERM :: Errno
- ePFNOSUPPORT :: Errno
- ePIPE :: Errno
- ePROCLIM :: Errno
- ePROCUNAVAIL :: Errno
- ePROGMISMATCH :: Errno
- ePROGUNAVAIL :: Errno
- ePROTO :: Errno
- ePROTONOSUPPORT :: Errno
- ePROTOTYPE :: Errno
- eRANGE :: Errno
- eREMCHG :: Errno
- eREMOTE :: Errno
- eROFS :: Errno
- eRPCMISMATCH :: Errno
- eRREMOTE :: Errno
- eSHUTDOWN :: Errno
- eSOCKTNOSUPPORT :: Errno
- eSPIPE :: Errno
- eSRCH :: Errno
- eSRMNT :: Errno
- eSTALE :: Errno
- eTIME :: Errno
- eTIMEDOUT :: Errno
- eTOOMANYREFS :: Errno
- eTXTBSY :: Errno
- eUSERS :: Errno
- eWOULDBLOCK :: Errno
- eXDEV :: Errno
- isValidErrno :: Errno -> Bool
- getErrno :: IO Errno
- resetErrno :: IO ()
- errnoToIOError :: String -> Errno -> Maybe Handle -> Maybe String -> IOError
- throwErrno :: String -> IO a
- throwErrnoIf :: (a -> Bool) -> String -> IO a -> IO a
- throwErrnoIf_ :: (a -> Bool) -> String -> IO a -> IO ()
- throwErrnoIfRetry :: (a -> Bool) -> String -> IO a -> IO a
- throwErrnoIfRetry_ :: (a -> Bool) -> String -> IO a -> IO ()
- throwErrnoIfMinus1 :: Num a => String -> IO a -> IO a
- throwErrnoIfMinus1_ :: Num a => String -> IO a -> IO ()
- throwErrnoIfMinus1Retry :: Num a => String -> IO a -> IO a
- throwErrnoIfMinus1Retry_ :: Num a => String -> IO a -> IO ()
- throwErrnoIfNull :: String -> IO (Ptr a) -> IO (Ptr a)
- throwErrnoIfNullRetry :: String -> IO (Ptr a) -> IO (Ptr a)
- throwErrnoIfRetryMayBlock :: (a -> Bool) -> String -> IO a -> IO b -> IO a
- throwErrnoIfRetryMayBlock_ :: (a -> Bool) -> String -> IO a -> IO b -> IO ()
- throwErrnoIfMinus1RetryMayBlock :: Num a => String -> IO a -> IO b -> IO a
- throwErrnoIfMinus1RetryMayBlock_ :: Num a => String -> IO a -> IO b -> IO ()
- throwErrnoIfNullRetryMayBlock :: String -> IO (Ptr a) -> IO b -> IO (Ptr a)
- throwErrnoPath :: String -> FilePath -> IO a
- throwErrnoPathIf :: (a -> Bool) -> String -> FilePath -> IO a -> IO a
- throwErrnoPathIf_ :: (a -> Bool) -> String -> FilePath -> IO a -> IO ()
- throwErrnoPathIfNull :: String -> FilePath -> IO (Ptr a) -> IO (Ptr a)
- throwErrnoPathIfMinus1 :: Num a => String -> FilePath -> IO a -> IO a
- throwErrnoPathIfMinus1_ :: Num a => String -> FilePath -> IO a -> IO ()

# Haskell representations of `errno` values

newtype Errno

Haskell representation for `errno` values. The implementation is deliberately exposed, to allow users to add their own definitions of `Errno` values.

Constructors

Errno CInt |

Instances

Eq Errno |

## Common `errno` symbols

Different operating systems and/or C libraries often support different values of `errno`. This module defines the common values, but due to the open definition of `Errno` users may add definitions which are not predefined.

eOK :: Errno

e2BIG :: Errno

eACCES :: Errno

eADDRINUSE :: Errno

eADDRNOTAVAIL :: Errno

eADV :: Errno

eAFNOSUPPORT :: Errno

eAGAIN :: Errno

eALREADY :: Errno

eBADF :: Errno

eBADMSG :: Errno

eBADRPC :: Errno

eBUSY :: Errno

eCHILD :: Errno

eCOMM :: Errno

eCONNABORTED :: Errno

eCONNREFUSED :: Errno

eCONNRESET :: Errno

eDEADLK :: Errno

eDESTADDRREQ :: Errno

eDIRTY :: Errno

eDOM :: Errno

eDQUOT :: Errno

eEXIST :: Errno

eFAULT :: Errno

eFBIG :: Errno

eFTYPE :: Errno

eHOSTDOWN :: Errno

eHOSTUNREACH :: Errno

eIDRM :: Errno

eILSEQ :: Errno

eINPROGRESS :: Errno

eINTR :: Errno

eINVAL :: Errno

eIO :: Errno

eISCONN :: Errno

eISDIR :: Errno

eLOOP :: Errno

eMFILE :: Errno

eMLINK :: Errno

eMSGSIZE :: Errno

eMULTIHOP :: Errno

eNAMETOOLONG :: Errno

eNETDOWN :: Errno

eNETRESET :: Errno

eNETUNREACH :: Errno

eNFILE :: Errno

eNOBUFS :: Errno

eNODATA :: Errno

eNODEV :: Errno

eNOENT :: Errno

eNOEXEC :: Errno

eNOLCK :: Errno

eNOLINK :: Errno

eNOMEM :: Errno

eNOMSG :: Errno

eNONET :: Errno

eNOPROTOOPT :: Errno

eNOSPC :: Errno

eNOSR :: Errno

eNOSTR :: Errno

eNOSYS :: Errno

eNOTBLK :: Errno

eNOTCONN :: Errno

eNOTDIR :: Errno

eNOTEMPTY :: Errno

eNOTSOCK :: Errno

eNOTTY :: Errno

eNXIO :: Errno

eOPNOTSUPP :: Errno

ePERM :: Errno

ePFNOSUPPORT :: Errno

ePIPE :: Errno

ePROCLIM :: Errno

ePROCUNAVAIL :: Errno

ePROGMISMATCH :: Errno

ePROGUNAVAIL :: Errno

ePROTO :: Errno

ePROTONOSUPPORT :: Errno

ePROTOTYPE :: Errno

eRANGE :: Errno

eREMCHG :: Errno

eREMOTE :: Errno

eROFS :: Errno

eRPCMISMATCH :: Errno

eRREMOTE :: Errno

eSHUTDOWN :: Errno

eSOCKTNOSUPPORT :: Errno

eSPIPE :: Errno

eSRCH :: Errno

eSRMNT :: Errno

eSTALE :: Errno

eTIME :: Errno

eTIMEDOUT :: Errno

eTOOMANYREFS :: Errno

eTXTBSY :: Errno

eUSERS :: Errno

eWOULDBLOCK :: Errno

eXDEV :: Errno

## `Errno` functions

isValidErrno :: Errno -> Bool

Yield `True` if the given `Errno` value is valid on the system. This implies that the `Eq` instance of `Errno` is also system dependent as it is only defined for valid values of `Errno`.

getErrno :: IO Errno

Get the current value of `errno` in the current thread.

resetErrno :: IO ()

Reset the current thread's `errno` value to `eOK`.

errnoToIOError

Arguments

:: String | the location where the error occurred
-> Errno | the error number
-> Maybe Handle | optional handle associated with the error
-> Maybe String | optional filename associated with the error
-> IOError |

Construct an `IOError` based on the given `Errno` value. The optional information can be used to improve the accuracy of error messages.

throwErrno

Arguments

:: String | textual description of the error location
-> IO a |

Throw an `IOError` corresponding to the current value of `getErrno`.

## Guards for IO operations that may fail

throwErrnoIf

Arguments

:: (a -> Bool) | predicate to apply to the result value of the `IO` operation
-> String | textual description of the location
-> IO a | the `IO` operation to be executed
-> IO a |

Throw an `IOError` corresponding to the current value of `getErrno` if the result value of the `IO` action meets the given predicate.

throwErrnoIf_ :: (a -> Bool) -> String -> IO a -> IO ()

as `throwErrnoIf`, but discards the result of the `IO` action after error handling.

throwErrnoIfRetry :: (a -> Bool) -> String -> IO a -> IO a

as `throwErrnoIf`, but retry the `IO` action when it yields the error code `eINTR` - this amounts to the standard retry loop for interrupted POSIX system calls.

throwErrnoIfRetry_ :: (a -> Bool) -> String -> IO a -> IO ()

as `throwErrnoIfRetry`, but discards the result.

throwErrnoIfMinus1 :: Num a => String -> IO a -> IO a

Throw an `IOError` corresponding to the current value of `getErrno` if the `IO` action returns a result of `-1`.

throwErrnoIfMinus1_ :: Num a => String -> IO a -> IO ()

as `throwErrnoIfMinus1`, but discards the result.

throwErrnoIfMinus1Retry :: Num a => String -> IO a -> IO a

Throw an `IOError` corresponding to the current value of `getErrno` if the `IO` action returns a result of `-1`, but retries in case of an interrupted operation.

throwErrnoIfMinus1Retry_ :: Num a => String -> IO a -> IO ()

as `throwErrnoIfMinus1`, but discards the result.

throwErrnoIfNull :: String -> IO (Ptr a) -> IO (Ptr a)

Throw an `IOError` corresponding to the current value of `getErrno` if the `IO` action returns `nullPtr`.

throwErrnoIfNullRetry :: String -> IO (Ptr a) -> IO (Ptr a)

Throw an `IOError` corresponding to the current value of `getErrno` if the `IO` action returns `nullPtr`, but retry in case of an interrupted operation.

throwErrnoIfRetryMayBlock

Arguments

:: (a -> Bool) | predicate to apply to the result value of the `IO` operation
-> String | textual description of the location
-> IO a | the `IO` operation to be executed
-> IO b | action to execute before retrying if an immediate retry would block
-> IO a |

as `throwErrnoIfRetry`, but additionally if the operation yields the error code `eAGAIN` or `eWOULDBLOCK`, an alternative action is executed before retrying.

throwErrnoIfRetryMayBlock_ :: (a -> Bool) -> String -> IO a -> IO b -> IO ()

as `throwErrnoIfRetryMayBlock`, but discards the result.

throwErrnoIfMinus1RetryMayBlock :: Num a => String -> IO a -> IO b -> IO a

as `throwErrnoIfMinus1Retry`, but checks for operations that would block.

throwErrnoIfMinus1RetryMayBlock_ :: Num a => String -> IO a -> IO b -> IO ()

as `throwErrnoIfMinus1RetryMayBlock`, but discards the result.

throwErrnoIfNullRetryMayBlock :: String -> IO (Ptr a) -> IO b -> IO (Ptr a)

as `throwErrnoIfNullRetry`, but checks for operations that would block.

throwErrnoPath :: String -> FilePath -> IO a

as `throwErrno`, but exceptions include the given path when appropriate.

throwErrnoPathIf :: (a -> Bool) -> String -> FilePath -> IO a -> IO a

as `throwErrnoIf`, but exceptions include the given path when appropriate.

throwErrnoPathIf_ :: (a -> Bool) -> String -> FilePath -> IO a -> IO ()

as `throwErrnoIf_`, but exceptions include the given path when appropriate.

throwErrnoPathIfNull :: String -> FilePath -> IO (Ptr a) -> IO (Ptr a)

as `throwErrnoIfNull`, but exceptions include the given path when appropriate.

throwErrnoPathIfMinus1 :: Num a => String -> FilePath -> IO a -> IO a

as `throwErrnoIfMinus1`, but exceptions include the given path when appropriate.

throwErrnoPathIfMinus1_ :: Num a => String -> FilePath -> IO a -> IO ()

as `throwErrnoIfMinus1_`, but exceptions include the given path when appropriate.