1 {-# OPTIONS_GHC -XNoImplicitPrelude -XBangPatterns #-}
2 -----------------------------------------------------------------------------
4 -- Module : GHC.IO.Device
5 -- Copyright : (c) The University of Glasgow, 1994-2008
6 -- License : see libraries/base/LICENSE
8 -- Maintainer : libraries@haskell.org
9 -- Stability : internal
10 -- Portability : non-portable
12 -- Type classes for I/O providers.
14 -----------------------------------------------------------------------------
16 module GHC.IO.Device (
23 #ifdef __GLASGOW_HASKELL__
34 import {-# SOURCE #-} GHC.IO.Exception ( unsupportedOperation )
39 import Control.Exception.Base
40 unsupportedOperation = userError "unsupported operation"
43 -- | A low-level I/O provider where the data is bytes in memory.
45 -- | Read up to the specified number of bytes, returning the number
46 -- of bytes actually read. This function should only block if there
47 -- is no data available. If there is not enough data available,
48 -- then the function should just return the available data. A return
49 -- value of zero indicates that the end of the data stream (e.g. end
50 -- of file) has been reached.
51 read :: a -> Ptr Word8 -> Int -> IO Int
53 -- | Read up to the specified number of bytes, returning the number
54 -- of bytes actually read, or 'Nothing' if the end of the stream has
56 readNonBlocking :: a -> Ptr Word8 -> Int -> IO (Maybe Int)
58 -- | Write the specified number of bytes.
59 write :: a -> Ptr Word8 -> Int -> IO ()
61 -- | Write up to the specified number of bytes without blocking. Returns
62 -- the actual number of bytes written.
63 writeNonBlocking :: a -> Ptr Word8 -> Int -> IO Int
66 -- | I/O operations required for implementing a 'Handle'.
67 class IODevice a where
68 -- | @ready dev write msecs@ returns 'True' if the device has data
69 -- to read (if @write@ is 'False') or space to write new data (if
70 -- @write@ is 'True'). @msecs@ specifies how long to wait, in
73 ready :: a -> Bool -> Int -> IO Bool
75 -- | closes the device. Further operations on the device should
76 -- produce exceptions.
79 -- | returns 'True' if the device is a terminal or console.
80 isTerminal :: a -> IO Bool
81 isTerminal _ = return False
83 -- | returns 'True' if the device supports 'seek' operations.
84 isSeekable :: a -> IO Bool
85 isSeekable _ = return False
87 -- | seek to the specified position in the data.
88 seek :: a -> SeekMode -> Integer -> IO ()
89 seek _ _ _ = ioe_unsupportedOperation
91 -- | return the current position in the data.
92 tell :: a -> IO Integer
93 tell _ = ioe_unsupportedOperation
95 -- | return the size of the data.
96 getSize :: a -> IO Integer
97 getSize _ = ioe_unsupportedOperation
99 -- | change the size of the data.
100 setSize :: a -> Integer -> IO ()
101 setSize _ _ = ioe_unsupportedOperation
103 -- | for terminal devices, changes whether characters are echoed on
105 setEcho :: a -> Bool -> IO ()
106 setEcho _ _ = ioe_unsupportedOperation
108 -- | returns the current echoing status.
109 getEcho :: a -> IO Bool
110 getEcho _ = ioe_unsupportedOperation
112 -- | some devices (e.g. terminals) support a "raw" mode where
113 -- characters entered are immediately made available to the program.
114 -- If available, this operations enables raw mode.
115 setRaw :: a -> Bool -> IO ()
116 setRaw _ _ = ioe_unsupportedOperation
118 -- | returns the 'IODeviceType' corresponding to this device.
119 devType :: a -> IO IODeviceType
121 -- | duplicates the device, if possible. The new device is expected
122 -- to share a file pointer with the original device (like Unix @dup@).
124 dup _ = ioe_unsupportedOperation
126 -- | @dup2 source target@ replaces the target device with the source
127 -- device. The target device is closed first, if necessary, and then
128 -- it is made into a duplicate of the first device (like Unix @dup2@).
129 dup2 :: a -> a -> IO a
130 dup2 _ _ = ioe_unsupportedOperation
132 ioe_unsupportedOperation :: IO a
133 ioe_unsupportedOperation = throwIO unsupportedOperation
142 -- -----------------------------------------------------------------------------
145 -- | A mode that determines the effect of 'hSeek' @hdl mode i@, as follows:
147 = AbsoluteSeek -- ^ the position of @hdl@ is set to @i@.
148 | RelativeSeek -- ^ the position of @hdl@ is set to offset @i@
149 -- from the current position.
150 | SeekFromEnd -- ^ the position of @hdl@ is set to offset @i@
151 -- from the end of the file.
152 deriving (Eq, Ord, Ix, Enum, Read, Show)