base-4.5.0.0: Basic libraries

Portability | portable
Stability | provisional
Maintainer | ffi@haskell.org
Safe Haskell | Trustworthy

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, eXDEV, eWOULDBLOCK, eUSERS, eTXTBSY, eTOOMANYREFS, eTIMEDOUT, eTIME, eSTALE, eSRMNT, eSRCH, eSPIPE, eSOCKTNOSUPPORT, eSHUTDOWN, eRREMOTE, eRPCMISMATCH, eROFS, eREMOTE, eREMCHG, eRANGE, ePROTOTYPE, ePROTONOSUPPORT, ePROTO, ePROGUNAVAIL, ePROGMISMATCH, ePROCUNAVAIL, ePROCLIM, ePIPE, ePFNOSUPPORT, ePERM, eOPNOTSUPP, eNXIO, eNOTTY, eNOTSOCK, eNOTEMPTY, eNOTDIR, eNOTCONN, eNOTBLK, eNOSYS, eNOSTR, eNOSR, eNOSPC, eNOPROTOOPT, eNONET, eNOMSG, eNOMEM, eNOLINK, eNOLCK, eNOEXEC, eNOENT, eNODEV, eNODATA, eNOBUFS, eNFILE, eNETUNREACH, eNETRESET, eNETDOWN, eNAMETOOLONG, eMULTIHOP, eMSGSIZE, eMLINK, eMFILE, eLOOP, eISDIR, eISCONN, eIO, eINVAL, eINTR, eINPROGRESS, eILSEQ, eIDRM, eHOSTUNREACH, eHOSTDOWN, eFTYPE, eFBIG, eFAULT, eEXIST, eDQUOT, eDOM, eDIRTY, eDESTADDRREQ, eDEADLK, eCONNRESET, eCONNREFUSED, eCONNABORTED, eCOMM, eCHILD, eBUSY, eBADRPC, eBADMSG, eBADF, eALREADY, eAGAIN, eAFNOSUPPORT, eADV, eADDRNOTAVAIL, eADDRINUSE, eACCES, e2BIG :: 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 :: (Eq a, Num a) => String -> IO a -> IO a
- throwErrnoIfMinus1_ :: (Eq a, Num a) => String -> IO a -> IO ()
- throwErrnoIfMinus1Retry :: (Eq a, Num a) => String -> IO a -> IO a
- throwErrnoIfMinus1Retry_ :: (Eq a, 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 :: (Eq a, Num a) => String -> IO a -> IO b -> IO a
- throwErrnoIfMinus1RetryMayBlock_ :: (Eq a, 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 :: (Eq a, Num a) => String -> FilePath -> IO a -> IO a
- throwErrnoPathIfMinus1_ :: (Eq a, 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, eXDEV, eWOULDBLOCK, eUSERS, eTXTBSY, eTOOMANYREFS, eTIMEDOUT, eTIME, eSTALE, eSRMNT, eSRCH, eSPIPE, eSOCKTNOSUPPORT, eSHUTDOWN, eRREMOTE, eRPCMISMATCH, eROFS, eREMOTE, eREMCHG, eRANGE, ePROTOTYPE, ePROTONOSUPPORT, ePROTO, ePROGUNAVAIL, ePROGMISMATCH, ePROCUNAVAIL, ePROCLIM, ePIPE, ePFNOSUPPORT, ePERM, eOPNOTSUPP, eNXIO, eNOTTY, eNOTSOCK, eNOTEMPTY, eNOTDIR, eNOTCONN, eNOTBLK, eNOSYS, eNOSTR, eNOSR, eNOSPC, eNOPROTOOPT, eNONET, eNOMSG, eNOMEM, eNOLINK, eNOLCK, eNOEXEC, eNOENT, eNODEV, eNODATA, eNOBUFS, eNFILE, eNETUNREACH, eNETRESET, eNETDOWN, eNAMETOOLONG, eMULTIHOP, eMSGSIZE, eMLINK, eMFILE, eLOOP, eISDIR, eISCONN, eIO, eINVAL, eINTR, eINPROGRESS, eILSEQ, eIDRM, eHOSTUNREACH, eHOSTDOWN, eFTYPE, eFBIG, eFAULT, eEXIST, eDQUOT, eDOM, eDIRTY, eDESTADDRREQ, eDEADLK, eCONNRESET, eCONNREFUSED, eCONNABORTED, eCOMM, eCHILD, eBUSY, eBADRPC, eBADMSG, eBADF, eALREADY, eAGAIN, eAFNOSUPPORT, eADV, eADDRNOTAVAIL, eADDRINUSE, eACCES, e2BIG :: 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 :: (Eq a, 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_ :: (Eq a, Num a) => String -> IO a -> IO ()

as `throwErrnoIfMinus1`, but discards the result.

throwErrnoIfMinus1Retry :: (Eq a, 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_ :: (Eq a, 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 :: (Eq a, Num a) => String -> IO a -> IO b -> IO a

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

throwErrnoIfMinus1RetryMayBlock_ :: (Eq a, 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 :: (Eq a, Num a) => String -> FilePath -> IO a -> IO a

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

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

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