SafeHaskell: Added SafeHaskell to base
[ghc.git] / libraries / base / GHC / IO / Device.hs
1 {-# LANGUAGE Trustworthy #-}
2 {-# LANGUAGE CPP, NoImplicitPrelude, BangPatterns #-}
3
4 -----------------------------------------------------------------------------
5 -- |
6 -- Module : GHC.IO.Device
7 -- Copyright : (c) The University of Glasgow, 1994-2008
8 -- License : see libraries/base/LICENSE
9 --
10 -- Maintainer : libraries@haskell.org
11 -- Stability : internal
12 -- Portability : non-portable
13 --
14 -- Type classes for I/O providers.
15 --
16 -----------------------------------------------------------------------------
17
18 module GHC.IO.Device (
19 RawIO(..),
20 IODevice(..),
21 IODeviceType(..),
22 SeekMode(..)
23 ) where
24
25 #ifdef __GLASGOW_HASKELL__
26 import GHC.Base
27 import GHC.Word
28 import GHC.Arr
29 import GHC.Enum
30 import GHC.Read
31 import GHC.Show
32 import GHC.Ptr
33 import Data.Maybe
34 import GHC.Num
35 import GHC.IO
36 import {-# SOURCE #-} GHC.IO.Exception ( unsupportedOperation )
37 #endif
38 #ifdef __NHC__
39 import Foreign
40 import Ix
41 import Control.Exception.Base
42 unsupportedOperation = userError "unsupported operation"
43 #endif
44
45 -- | A low-level I/O provider where the data is bytes in memory.
46 class RawIO a where
47 -- | Read up to the specified number of bytes, returning the number
48 -- of bytes actually read. This function should only block if there
49 -- is no data available. If there is not enough data available,
50 -- then the function should just return the available data. A return
51 -- value of zero indicates that the end of the data stream (e.g. end
52 -- of file) has been reached.
53 read :: a -> Ptr Word8 -> Int -> IO Int
54
55 -- | Read up to the specified number of bytes, returning the number
56 -- of bytes actually read, or 'Nothing' if the end of the stream has
57 -- been reached.
58 readNonBlocking :: a -> Ptr Word8 -> Int -> IO (Maybe Int)
59
60 -- | Write the specified number of bytes.
61 write :: a -> Ptr Word8 -> Int -> IO ()
62
63 -- | Write up to the specified number of bytes without blocking. Returns
64 -- the actual number of bytes written.
65 writeNonBlocking :: a -> Ptr Word8 -> Int -> IO Int
66
67
68 -- | I/O operations required for implementing a 'Handle'.
69 class IODevice a where
70 -- | @ready dev write msecs@ returns 'True' if the device has data
71 -- to read (if @write@ is 'False') or space to write new data (if
72 -- @write@ is 'True'). @msecs@ specifies how long to wait, in
73 -- milliseconds.
74 --
75 ready :: a -> Bool -> Int -> IO Bool
76
77 -- | closes the device. Further operations on the device should
78 -- produce exceptions.
79 close :: a -> IO ()
80
81 -- | returns 'True' if the device is a terminal or console.
82 isTerminal :: a -> IO Bool
83 isTerminal _ = return False
84
85 -- | returns 'True' if the device supports 'seek' operations.
86 isSeekable :: a -> IO Bool
87 isSeekable _ = return False
88
89 -- | seek to the specified position in the data.
90 seek :: a -> SeekMode -> Integer -> IO ()
91 seek _ _ _ = ioe_unsupportedOperation
92
93 -- | return the current position in the data.
94 tell :: a -> IO Integer
95 tell _ = ioe_unsupportedOperation
96
97 -- | return the size of the data.
98 getSize :: a -> IO Integer
99 getSize _ = ioe_unsupportedOperation
100
101 -- | change the size of the data.
102 setSize :: a -> Integer -> IO ()
103 setSize _ _ = ioe_unsupportedOperation
104
105 -- | for terminal devices, changes whether characters are echoed on
106 -- the device.
107 setEcho :: a -> Bool -> IO ()
108 setEcho _ _ = ioe_unsupportedOperation
109
110 -- | returns the current echoing status.
111 getEcho :: a -> IO Bool
112 getEcho _ = ioe_unsupportedOperation
113
114 -- | some devices (e.g. terminals) support a "raw" mode where
115 -- characters entered are immediately made available to the program.
116 -- If available, this operations enables raw mode.
117 setRaw :: a -> Bool -> IO ()
118 setRaw _ _ = ioe_unsupportedOperation
119
120 -- | returns the 'IODeviceType' corresponding to this device.
121 devType :: a -> IO IODeviceType
122
123 -- | duplicates the device, if possible. The new device is expected
124 -- to share a file pointer with the original device (like Unix @dup@).
125 dup :: a -> IO a
126 dup _ = ioe_unsupportedOperation
127
128 -- | @dup2 source target@ replaces the target device with the source
129 -- device. The target device is closed first, if necessary, and then
130 -- it is made into a duplicate of the first device (like Unix @dup2@).
131 dup2 :: a -> a -> IO a
132 dup2 _ _ = ioe_unsupportedOperation
133
134 ioe_unsupportedOperation :: IO a
135 ioe_unsupportedOperation = throwIO unsupportedOperation
136
137 -- | Type of a device that can be used to back a
138 -- 'GHC.IO.Handle.Handle' (see also 'GHC.IO.Handle.mkFileHandle'). The
139 -- standard libraries provide creation of 'GHC.IO.Handle.Handle's via
140 -- Posix file operations with file descriptors (see
141 -- 'GHC.IO.Handle.FD.mkHandleFromFD') with FD being the underlying
142 -- 'GHC.IO.Device.IODevice' instance.
143 --
144 -- Users may provide custom instances of 'GHC.IO.Device.IODevice'
145 -- which are expected to conform the following rules:
146
147 data IODeviceType
148 = Directory -- ^ The standard libraries do not have direct support
149 -- for this device type, but a user implementation is
150 -- expected to provide a list of file names in
151 -- the directory, in any order, separated by @'\0'@
152 -- characters, excluding the @"."@ and @".."@ names. See
153 -- also 'System.Directory.getDirectoryContents'. Seek
154 -- operations are not supported on directories (other
155 -- than to the zero position).
156 | Stream -- ^ A duplex communications channel (results in
157 -- creation of a duplex 'GHC.IO.Handle.Handle'). The
158 -- standard libraries use this device type when
159 -- creating 'GHC.IO.Handle.Handle's for open sockets.
160 | RegularFile -- ^ A file that may be read or written, and also
161 -- may be seekable.
162 | RawDevice -- ^ A "raw" (disk) device which supports block binary
163 -- read and write operations and may be seekable only
164 -- to positions of certain granularity (block-
165 -- aligned).
166 deriving (Eq)
167
168 -- -----------------------------------------------------------------------------
169 -- SeekMode type
170
171 -- | A mode that determines the effect of 'hSeek' @hdl mode i@.
172 data SeekMode
173 = AbsoluteSeek -- ^ the position of @hdl@ is set to @i@.
174 | RelativeSeek -- ^ the position of @hdl@ is set to offset @i@
175 -- from the current position.
176 | SeekFromEnd -- ^ the position of @hdl@ is set to offset @i@
177 -- from the end of the file.
178 deriving (Eq, Ord, Ix, Enum, Read, Show)