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