Remove Control.Parallel*, now in package parallel
[packages/random.git] / System / IO / Error.hs
1 {-# OPTIONS_GHC -fno-implicit-prelude #-}
2
3 -----------------------------------------------------------------------------
4 -- |
5 -- Module : System.IO.Error
6 -- Copyright : (c) The University of Glasgow 2001
7 -- License : BSD-style (see the file libraries/base/LICENSE)
8 --
9 -- Maintainer : libraries@haskell.org
10 -- Stability : provisional
11 -- Portability : portable
12 --
13 -- Standard IO Errors.
14 --
15 -----------------------------------------------------------------------------
16
17 module System.IO.Error (
18
19 -- * I\/O errors
20 IOError, -- = IOException
21
22 userError, -- :: String -> IOError
23
24 #ifndef __NHC__
25 mkIOError, -- :: IOErrorType -> String -> Maybe Handle
26 -- -> Maybe FilePath -> IOError
27
28 annotateIOError, -- :: IOError -> String -> Maybe Handle
29 -- -> Maybe FilePath -> IOError
30 #endif
31
32 -- ** Classifying I\/O errors
33 isAlreadyExistsError, -- :: IOError -> Bool
34 isDoesNotExistError,
35 isAlreadyInUseError,
36 isFullError,
37 isEOFError,
38 isIllegalOperation,
39 isPermissionError,
40 isUserError,
41
42 -- ** Attributes of I\/O errors
43 #ifndef __NHC__
44 ioeGetErrorType, -- :: IOError -> IOErrorType
45 ioeGetLocation, -- :: IOError -> String
46 #endif
47 ioeGetErrorString, -- :: IOError -> String
48 ioeGetHandle, -- :: IOError -> Maybe Handle
49 ioeGetFileName, -- :: IOError -> Maybe FilePath
50
51 #ifndef __NHC__
52 ioeSetErrorType, -- :: IOError -> IOErrorType -> IOError
53 ioeSetErrorString, -- :: IOError -> String -> IOError
54 ioeSetLocation, -- :: IOError -> String -> IOError
55 ioeSetHandle, -- :: IOError -> Handle -> IOError
56 ioeSetFileName, -- :: IOError -> FilePath -> IOError
57 #endif
58
59 -- * Types of I\/O error
60 IOErrorType, -- abstract
61
62 alreadyExistsErrorType, -- :: IOErrorType
63 doesNotExistErrorType,
64 alreadyInUseErrorType,
65 fullErrorType,
66 eofErrorType,
67 illegalOperationErrorType,
68 permissionErrorType,
69 userErrorType,
70
71 -- ** 'IOErrorType' predicates
72 isAlreadyExistsErrorType, -- :: IOErrorType -> Bool
73 isDoesNotExistErrorType,
74 isAlreadyInUseErrorType,
75 isFullErrorType,
76 isEOFErrorType,
77 isIllegalOperationErrorType,
78 isPermissionErrorType,
79 isUserErrorType,
80
81 -- * Throwing and catching I\/O errors
82
83 ioError, -- :: IOError -> IO a
84
85 catch, -- :: IO a -> (IOError -> IO a) -> IO a
86 try, -- :: IO a -> IO (Either IOError a)
87
88 #ifndef __NHC__
89 modifyIOError, -- :: (IOError -> IOError) -> IO a -> IO a
90 #endif
91 ) where
92
93 import Data.Either
94 import Data.Maybe
95
96 #ifdef __GLASGOW_HASKELL__
97 import GHC.Base
98 import GHC.IOBase
99 import GHC.Exception
100 import Text.Show
101 #endif
102
103 #ifdef __HUGS__
104 import Hugs.Prelude(Handle, IOException(..), IOErrorType(..))
105 #endif
106
107 #ifdef __NHC__
108 import IO
109 ( IOError ()
110 , try
111 , ioError
112 , userError
113 , isAlreadyExistsError -- :: IOError -> Bool
114 , isDoesNotExistError
115 , isAlreadyInUseError
116 , isFullError
117 , isEOFError
118 , isIllegalOperation
119 , isPermissionError
120 , isUserError
121 , ioeGetErrorString -- :: IOError -> String
122 , ioeGetHandle -- :: IOError -> Maybe Handle
123 , ioeGetFileName -- :: IOError -> Maybe FilePath
124 )
125 --import Data.Maybe (fromJust)
126 --import Control.Monad (MonadPlus(mplus))
127 #endif
128
129 -- | The construct 'try' @comp@ exposes IO errors which occur within a
130 -- computation, and which are not fully handled.
131 --
132 -- Non-I\/O exceptions are not caught by this variant; to catch all
133 -- exceptions, use 'Control.Exception.try' from "Control.Exception".
134
135 #ifndef __NHC__
136 try :: IO a -> IO (Either IOError a)
137 try f = catch (do r <- f
138 return (Right r))
139 (return . Left)
140 #endif
141
142 #if defined(__GLASGOW_HASKELL__) || defined(__HUGS__)
143 -- -----------------------------------------------------------------------------
144 -- Constructing an IOError
145
146 -- | Construct an 'IOError' of the given type where the second argument
147 -- describes the error location and the third and fourth argument
148 -- contain the file handle and file path of the file involved in the
149 -- error if applicable.
150 mkIOError :: IOErrorType -> String -> Maybe Handle -> Maybe FilePath -> IOError
151 mkIOError t location maybe_hdl maybe_filename =
152 IOError{ ioe_type = t,
153 ioe_location = location,
154 ioe_description = "",
155 ioe_handle = maybe_hdl,
156 ioe_filename = maybe_filename
157 }
158 #ifdef __NHC__
159 mkIOError EOF location maybe_hdl maybe_filename =
160 EOFError location (fromJust maybe_hdl)
161 mkIOError UserError location maybe_hdl maybe_filename =
162 UserError location ""
163 mkIOError t location maybe_hdl maybe_filename =
164 NHC.FFI.mkIOError location maybe_filename maybe_handle (ioeTypeToInt t)
165 where
166 ioeTypeToInt AlreadyExists = fromEnum EEXIST
167 ioeTypeToInt NoSuchThing = fromEnum ENOENT
168 ioeTypeToInt ResourceBusy = fromEnum EBUSY
169 ioeTypeToInt ResourceExhausted = fromEnum ENOSPC
170 ioeTypeToInt IllegalOperation = fromEnum EPERM
171 ioeTypeToInt PermissionDenied = fromEnum EACCES
172 #endif
173 #endif /* __GLASGOW_HASKELL__ || __HUGS__ */
174
175 #ifndef __NHC__
176 -- -----------------------------------------------------------------------------
177 -- IOErrorType
178
179 -- | An error indicating that an 'IO' operation failed because
180 -- one of its arguments already exists.
181 isAlreadyExistsError :: IOError -> Bool
182 isAlreadyExistsError = isAlreadyExistsErrorType . ioeGetErrorType
183
184 -- | An error indicating that an 'IO' operation failed because
185 -- one of its arguments does not exist.
186 isDoesNotExistError :: IOError -> Bool
187 isDoesNotExistError = isDoesNotExistErrorType . ioeGetErrorType
188
189 -- | An error indicating that an 'IO' operation failed because
190 -- one of its arguments is a single-use resource, which is already
191 -- being used (for example, opening the same file twice for writing
192 -- might give this error).
193 isAlreadyInUseError :: IOError -> Bool
194 isAlreadyInUseError = isAlreadyInUseErrorType . ioeGetErrorType
195
196 -- | An error indicating that an 'IO' operation failed because
197 -- the device is full.
198 isFullError :: IOError -> Bool
199 isFullError = isFullErrorType . ioeGetErrorType
200
201 -- | An error indicating that an 'IO' operation failed because
202 -- the end of file has been reached.
203 isEOFError :: IOError -> Bool
204 isEOFError = isEOFErrorType . ioeGetErrorType
205
206 -- | An error indicating that an 'IO' operation failed because
207 -- the operation was not possible.
208 -- Any computation which returns an 'IO' result may fail with
209 -- 'isIllegalOperation'. In some cases, an implementation will not be
210 -- able to distinguish between the possible error causes. In this case
211 -- it should fail with 'isIllegalOperation'.
212 isIllegalOperation :: IOError -> Bool
213 isIllegalOperation = isIllegalOperationErrorType . ioeGetErrorType
214
215 -- | An error indicating that an 'IO' operation failed because
216 -- the user does not have sufficient operating system privilege
217 -- to perform that operation.
218 isPermissionError :: IOError -> Bool
219 isPermissionError = isPermissionErrorType . ioeGetErrorType
220
221 -- | A programmer-defined error value constructed using 'userError'.
222 isUserError :: IOError -> Bool
223 isUserError = isUserErrorType . ioeGetErrorType
224 #endif /* __NHC__ */
225
226 -- -----------------------------------------------------------------------------
227 -- IOErrorTypes
228
229 #ifdef __NHC__
230 data IOErrorType = AlreadyExists | NoSuchThing | ResourceBusy
231 | ResourceExhausted | EOF | IllegalOperation
232 | PermissionDenied | UserError
233 #endif
234
235 -- | I\/O error where the operation failed because one of its arguments
236 -- already exists.
237 alreadyExistsErrorType :: IOErrorType
238 alreadyExistsErrorType = AlreadyExists
239
240 -- | I\/O error where the operation failed because one of its arguments
241 -- does not exist.
242 doesNotExistErrorType :: IOErrorType
243 doesNotExistErrorType = NoSuchThing
244
245 -- | I\/O error where the operation failed because one of its arguments
246 -- is a single-use resource, which is already being used.
247 alreadyInUseErrorType :: IOErrorType
248 alreadyInUseErrorType = ResourceBusy
249
250 -- | I\/O error where the operation failed because the device is full.
251 fullErrorType :: IOErrorType
252 fullErrorType = ResourceExhausted
253
254 -- | I\/O error where the operation failed because the end of file has
255 -- been reached.
256 eofErrorType :: IOErrorType
257 eofErrorType = EOF
258
259 -- | I\/O error where the operation is not possible.
260 illegalOperationErrorType :: IOErrorType
261 illegalOperationErrorType = IllegalOperation
262
263 -- | I\/O error where the operation failed because the user does not
264 -- have sufficient operating system privilege to perform that operation.
265 permissionErrorType :: IOErrorType
266 permissionErrorType = PermissionDenied
267
268 -- | I\/O error that is programmer-defined.
269 userErrorType :: IOErrorType
270 userErrorType = UserError
271
272 -- -----------------------------------------------------------------------------
273 -- IOErrorType predicates
274
275 -- | I\/O error where the operation failed because one of its arguments
276 -- already exists.
277 isAlreadyExistsErrorType :: IOErrorType -> Bool
278 isAlreadyExistsErrorType AlreadyExists = True
279 isAlreadyExistsErrorType _ = False
280
281 -- | I\/O error where the operation failed because one of its arguments
282 -- does not exist.
283 isDoesNotExistErrorType :: IOErrorType -> Bool
284 isDoesNotExistErrorType NoSuchThing = True
285 isDoesNotExistErrorType _ = False
286
287 -- | I\/O error where the operation failed because one of its arguments
288 -- is a single-use resource, which is already being used.
289 isAlreadyInUseErrorType :: IOErrorType -> Bool
290 isAlreadyInUseErrorType ResourceBusy = True
291 isAlreadyInUseErrorType _ = False
292
293 -- | I\/O error where the operation failed because the device is full.
294 isFullErrorType :: IOErrorType -> Bool
295 isFullErrorType ResourceExhausted = True
296 isFullErrorType _ = False
297
298 -- | I\/O error where the operation failed because the end of file has
299 -- been reached.
300 isEOFErrorType :: IOErrorType -> Bool
301 isEOFErrorType EOF = True
302 isEOFErrorType _ = False
303
304 -- | I\/O error where the operation is not possible.
305 isIllegalOperationErrorType :: IOErrorType -> Bool
306 isIllegalOperationErrorType IllegalOperation = True
307 isIllegalOperationErrorType _ = False
308
309 -- | I\/O error where the operation failed because the user does not
310 -- have sufficient operating system privilege to perform that operation.
311 isPermissionErrorType :: IOErrorType -> Bool
312 isPermissionErrorType PermissionDenied = True
313 isPermissionErrorType _ = False
314
315 -- | I\/O error that is programmer-defined.
316 isUserErrorType :: IOErrorType -> Bool
317 isUserErrorType UserError = True
318 isUserErrorType _ = False
319
320 -- -----------------------------------------------------------------------------
321 -- Miscellaneous
322
323 #if defined(__GLASGOW_HASKELL__) || defined(__HUGS__)
324 ioeGetErrorType :: IOError -> IOErrorType
325 ioeGetErrorString :: IOError -> String
326 ioeGetLocation :: IOError -> String
327 ioeGetHandle :: IOError -> Maybe Handle
328 ioeGetFileName :: IOError -> Maybe FilePath
329
330 ioeGetErrorType ioe = ioe_type ioe
331
332 ioeGetErrorString ioe
333 | isUserErrorType (ioe_type ioe) = ioe_description ioe
334 | otherwise = show (ioe_type ioe)
335
336 ioeGetLocation ioe = ioe_location ioe
337
338 ioeGetHandle ioe = ioe_handle ioe
339
340 ioeGetFileName ioe = ioe_filename ioe
341
342 ioeSetErrorType :: IOError -> IOErrorType -> IOError
343 ioeSetErrorString :: IOError -> String -> IOError
344 ioeSetLocation :: IOError -> String -> IOError
345 ioeSetHandle :: IOError -> Handle -> IOError
346 ioeSetFileName :: IOError -> FilePath -> IOError
347
348 ioeSetErrorType ioe errtype = ioe{ ioe_type = errtype }
349 ioeSetErrorString ioe str = ioe{ ioe_description = str }
350 ioeSetLocation ioe str = ioe{ ioe_location = str }
351 ioeSetHandle ioe hdl = ioe{ ioe_handle = Just hdl }
352 ioeSetFileName ioe filename = ioe{ ioe_filename = Just filename }
353
354 -- | Catch any 'IOError' that occurs in the computation and throw a
355 -- modified version.
356 modifyIOError :: (IOError -> IOError) -> IO a -> IO a
357 modifyIOError f io = catch io (\e -> ioError (f e))
358
359 -- -----------------------------------------------------------------------------
360 -- annotating an IOError
361
362 -- | Adds a location description and maybe a file path and file handle
363 -- to an 'IOError'. If any of the file handle or file path is not given
364 -- the corresponding value in the 'IOError' remains unaltered.
365 annotateIOError :: IOError
366 -> String
367 -> Maybe Handle
368 -> Maybe FilePath
369 -> IOError
370 annotateIOError (IOError ohdl errTy _ str opath) loc hdl path =
371 IOError (hdl `mplus` ohdl) errTy loc str (path `mplus` opath)
372 where
373 Nothing `mplus` ys = ys
374 xs `mplus` _ = xs
375 #endif /* __GLASGOW_HASKELL__ || __HUGS__ */
376
377 #if 0 /*__NHC__*/
378 annotateIOError (IOError msg file hdl code) msg' file' hdl' =
379 IOError (msg++'\n':msg') (file`mplus`file') (hdl`mplus`hdl') code
380 annotateIOError (EOFError msg hdl) msg' file' hdl' =
381 EOFError (msg++'\n':msg') (hdl`mplus`hdl')
382 annotateIOError (UserError loc msg) msg' file' hdl' =
383 UserError loc (msg++'\n':msg')
384 annotateIOError (PatternError loc) msg' file' hdl' =
385 PatternError (loc++'\n':msg')
386 #endif