4.5. CError

The module CError facillitates C-specific error handling, which essentially entails handling of the values of the variable errno. All definitions are together with the remainder of the C-specific marshalling support also available via the module CForeign (Section 4.6).

In Haskell land, values of the C errno are represented by the type Errno.

newtype Errno = Errno CInt  -- instances: Eq

The implementation of Errno is disclosed on purpose. 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 definition, which are not predefined. The predefined values are the following:

eOK, e2BIG, eACCES, eADDRINUSE, eADDRNOTAVAIL, eADV, eAFNOSUPPORT, eAGAIN, 
  eALREADY, eBADF, eBADMSG, eBADRPC, eBUSY, eCHILD, eCOMM, eCONNABORTED, 
  eCONNREFUSED, eCONNRESET, eDEADLK, eDESTADDRREQ, eDIRTY, eDOM, eDQUOT, 
  eEXIST, eFAULT, eFBIG, eFTYPE, eHOSTDOWN, eHOSTUNREACH, eIDRM, eILSEQ, 
  eINPROGRESS, eINTR, eINVAL, eIO, eISCONN, eISDIR, eLOOP, eMFILE, eMLINK, 
  eMSGSIZE, eMULTIHOP, eNAMETOOLONG, eNETDOWN, eNETRESET, eNETUNREACH, 
  eNFILE, eNOBUFS, eNODATA, eNODEV, eNOENT, eNOEXEC, eNOLCK, eNOLINK, 
  eNOMEM, eNOMSG, eNONET, eNOPROTOOPT, eNOSPC, eNOSR, eNOSTR, eNOSYS, 
  eNOTBLK, eNOTCONN, eNOTDIR, eNOTEMPTY, eNOTSOCK, eNOTTY, eNXIO, 
  eOPNOTSUPP, ePERM, ePFNOSUPPORT, ePIPE, ePROCLIM, ePROCUNAVAIL, 
  ePROGMISMATCH, ePROGUNAVAIL, ePROTO, ePROTONOSUPPORT, ePROTOTYPE, 
  eRANGE, eREMCHG, eREMOTE, eROFS, eRPCMISMATCH, eRREMOTE, eSHUTDOWN, 
  eSOCKTNOSUPPORT, eSPIPE, eSRCH, eSRMNT, eSTALE, eTIME, eTIMEDOUT, 
  eTOOMANYREFS, eTXTBSY, eUSERS, eWOULDBLOCK, eXDEV
  :: Errno

The meaning of these values corresponds to that of the C constants of the same name - after dropping the leading "e".

The Eq instance of Errno is also OS-dependent as it is only defined for valid values of Errno. The validity of these values is determined by the following function:

isValidErrno :: Errno -> Bool

The functions isValidErrno yields True for all values of errno that have a defined meaning on the present system.

getErrno   :: IO Errno
resetErrno :: IO ()

The two functions getErrno and resetErrno obtain the current value of the errno variable and reset it to eOK, respectively. On Haskell system with thread support, these and the following operations manipulate thread-local instances of errno.

errnoToIOError :: String       -- location
               -> Errno        -- errno
               -> Maybe Handle -- handle
               -> Maybe String -- filename
               -> IOError

throwErrno     :: String -> IO a

The function errnoToIOError throws an IO exception based on the given Errno value. The first argument to the function should specify the location where the error occured and the third and fourth can be used to specify a file handle and filename in the course of whose's manipulation the error occured. This is optional information, which can be used to improve the accuracy of error messages. The function throwErrno applies errnoToIOError to the current value returned by getErrno. Its first argument specifies the location - no extra information about a file handle or filename can be provided in this case.

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)

The function throwErrnoIf behaves like throwErrno in case that the result of the IO action fulfils the predicate passed as a first argument. All variants of the function whose name ends with an underscore character behave like the version without the underscore in the name, but discard the result of the IO action. All variants ending in "Retry" do retry the IO action when they would usually throw eINTR - this amounts to the standard retry loop for interrupted POSIX system calls. Finally, throwErrnoIfMinus1 and its variants throw the current errno value (or possibly retry the action) when the result of the IO action is -1, whereas throwErrnoIfNull does so in case of a Ptr.nullPtr (Section 4.29).