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