GHC/IO/Device.hs

   1 {-# OPTIONS_GHC -XNoImplicitPrelude -XBangPatterns #-}
   2 {-# OPTIONS_HADDOCK hide #-}
   3 -----------------------------------------------------------------------------
   4 -- |
   5 -- Module      :  GHC.IO.Device
   6 -- Copyright   :  (c) The University of Glasgow, 1994-2008
   7 -- License     :  see libraries/base/LICENSE
   8 --
   9 -- Maintainer  :  libraries@haskell.org
  10 -- Stability   :  internal
  11 -- Portability :  non-portable
  12 --
  13 -- Type classes for I/O providers.
  14 --
  15 -----------------------------------------------------------------------------
  16
  17 module GHC.IO.Device (
  18     RawIO(..),
  19     IODevice(..),
  20     IODeviceType(..),
  21     SeekMode(..)
  22   ) where
  23
  24 import GHC.Base
  25 import GHC.Word
  26 import GHC.Arr
  27 import GHC.Enum
  28 import GHC.Read
  29 import GHC.Show
  30 import GHC.Ptr
  31 import Data.Maybe
  32 import GHC.Num
  33 import GHC.IO
  34 import {-# SOURCE #-} GHC.IO.Exception ( unsupportedOperation )
  35
  36 -- | A low-level I/O provider where the data is bytes in memory.
  37 class RawIO a where
  38   -- | Read up to the specified number of bytes, returning the number
  39   -- of bytes actually read.  This function should only block if there
  40   -- is no data available.  If there is not enough data available,
  41   -- then the function should just return the available data. A return
  42   -- value of zero indicates that the end of the data stream (e.g. end
  43   -- of file) has been reached.
  44   read                :: a -> Ptr Word8 -> Int -> IO Int
  45
  46   -- | Read up to the specified number of bytes, returning the number
  47   -- of bytes actually read, or 'Nothing' if the end of the stream has
  48   -- been reached.
  49   readNonBlocking     :: a -> Ptr Word8 -> Int -> IO (Maybe Int)
  50
  51   -- | Write the specified number of bytes.
  52   write               :: a -> Ptr Word8 -> Int -> IO ()
  53
  54   -- | Write up to the specified number of bytes without blocking.  Returns
  55   -- the actual number of bytes written.
  56   writeNonBlocking    :: a -> Ptr Word8 -> Int -> IO Int
  57
  58
  59 -- | I/O operations required for implementing a 'Handle'.
  60 class IODevice a where
  61   -- | @ready dev write msecs@ returns 'True' if the device has data
  62   -- to read (if @write@ is 'False') or space to write new data (if
  63   -- @write@ is 'True').  @msecs@ specifies how long to wait, in
  64   -- milliseconds.
  65   --
  66   ready :: a -> Bool -> Int -> IO Bool
  67
  68   -- | closes the device.  Further operations on the device should
  69   -- produce exceptions.
  70   close :: a -> IO ()
  71
  72   -- | returns 'True' if the device is a terminal or console.
  73   isTerminal :: a -> IO Bool
  74   isTerminal _ = return False
  75
  76   -- | returns 'True' if the device supports 'seek' operations.
  77   isSeekable :: a -> IO Bool
  78   isSeekable _ = return False
  79
  80   -- | seek to the specified positing in the data.
  81   seek :: a -> SeekMode -> Integer -> IO ()
  82   seek _ _ _ = ioe_unsupportedOperation
  83
  84   -- | return the current position in the data.
  85   tell :: a -> IO Integer
  86   tell _ = ioe_unsupportedOperation
  87
  88   -- | return the size of the data.
  89   getSize :: a -> IO Integer
  90   getSize _ = ioe_unsupportedOperation
  91
  92   -- | change the size of the data.
  93   setSize :: a -> Integer -> IO ()
  94   setSize _ _ = ioe_unsupportedOperation
  95
  96   -- | for terminal devices, changes whether characters are echoed on
  97   -- the device.
  98   setEcho :: a -> Bool -> IO ()
  99   setEcho _ _ = ioe_unsupportedOperation
 100
 101   -- | returns the current echoing status.
 102   getEcho :: a -> IO Bool
 103   getEcho _ = ioe_unsupportedOperation
 104
 105   -- | some devices (e.g. terminals) support a "raw" mode where
 106   -- characters entered are immediately made available to the program.
 107   -- If available, this operations enables raw mode.
 108   setRaw :: a -> Bool -> IO ()
 109   setRaw _ _ = ioe_unsupportedOperation
 110
 111   -- | returns the 'IODeviceType' corresponding to this device.
 112   devType :: a -> IO IODeviceType
 113
 114   -- | duplicates the device, if possible.  The new device is expected
 115   -- to share a file pointer with the original device (like Unix @dup@).
 116   dup :: a -> IO a
 117   dup _ = ioe_unsupportedOperation
 118
 119   -- | @dup2 source target@ replaces the target device with the source
 120   -- device.  The target device is closed first, if necessary, and then
 121   -- it is made into a duplicate of the first device (like Unix @dup2@).
 122   dup2 :: a -> a -> IO a
 123   dup2 _ _ = ioe_unsupportedOperation
 124
 125 ioe_unsupportedOperation :: IO a
 126 ioe_unsupportedOperation = throwIO unsupportedOperation
 127
 128 data IODeviceType
 129   = Directory
 130   | Stream
 131   | RegularFile
 132   | RawDevice
 133   deriving (Eq)
 134
 135 -- -----------------------------------------------------------------------------
 136 -- SeekMode type
 137
 138 -- | A mode that determines the effect of 'hSeek' @hdl mode i@, as follows:
 139 data SeekMode
 140   = AbsoluteSeek        -- ^ the position of @hdl@ is set to @i@.
 141   | RelativeSeek        -- ^ the position of @hdl@ is set to offset @i@
 142                         -- from the current position.
 143   | SeekFromEnd         -- ^ the position of @hdl@ is set to offset @i@
 144                         -- from the end of the file.
 145     deriving (Eq, Ord, Ix, Enum, Read, Show)