GHC/IO/Device.hs

   1 {-# OPTIONS_GHC -XNoImplicitPrelude -XBangPatterns #-}
   2 -----------------------------------------------------------------------------
   3 -- |
   4 -- Module      :  GHC.IO.Device
   5 -- Copyright   :  (c) The University of Glasgow, 1994-2008
   6 -- License     :  see libraries/base/LICENSE
   7 --
   8 -- Maintainer  :  libraries@haskell.org
   9 -- Stability   :  internal
  10 -- Portability :  non-portable
  11 --
  12 -- Type classes for I/O providers.
  13 --
  14 -----------------------------------------------------------------------------
  15
  16 module GHC.IO.Device (
  17     RawIO(..),
  18     IODevice(..),
  19     IODeviceType(..),
  20     SeekMode(..)
  21   ) where
  22
  23 #ifdef __GLASGOW_HASKELL__
  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 #endif
  36 #ifdef __NHC__
  37 import Foreign
  38 import Ix
  39 import Control.Exception.Base
  40 unsupportedOperation = userError "unsupported operation"
  41 #endif
  42
  43 -- | A low-level I/O provider where the data is bytes in memory.
  44 class RawIO a where
  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
  52
  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
  55   -- been reached.
  56   readNonBlocking     :: a -> Ptr Word8 -> Int -> IO (Maybe Int)
  57
  58   -- | Write the specified number of bytes.
  59   write               :: a -> Ptr Word8 -> Int -> IO ()
  60
  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
  64
  65
  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
  71   -- milliseconds.
  72   --
  73   ready :: a -> Bool -> Int -> IO Bool
  74
  75   -- | closes the device.  Further operations on the device should
  76   -- produce exceptions.
  77   close :: a -> IO ()
  78
  79   -- | returns 'True' if the device is a terminal or console.
  80   isTerminal :: a -> IO Bool
  81   isTerminal _ = return False
  82
  83   -- | returns 'True' if the device supports 'seek' operations.
  84   isSeekable :: a -> IO Bool
  85   isSeekable _ = return False
  86
  87   -- | seek to the specified position in the data.
  88   seek :: a -> SeekMode -> Integer -> IO ()
  89   seek _ _ _ = ioe_unsupportedOperation
  90
  91   -- | return the current position in the data.
  92   tell :: a -> IO Integer
  93   tell _ = ioe_unsupportedOperation
  94
  95   -- | return the size of the data.
  96   getSize :: a -> IO Integer
  97   getSize _ = ioe_unsupportedOperation
  98
  99   -- | change the size of the data.
 100   setSize :: a -> Integer -> IO ()
 101   setSize _ _ = ioe_unsupportedOperation
 102
 103   -- | for terminal devices, changes whether characters are echoed on
 104   -- the device.
 105   setEcho :: a -> Bool -> IO ()
 106   setEcho _ _ = ioe_unsupportedOperation
 107
 108   -- | returns the current echoing status.
 109   getEcho :: a -> IO Bool
 110   getEcho _ = ioe_unsupportedOperation
 111
 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
 117
 118   -- | returns the 'IODeviceType' corresponding to this device.
 119   devType :: a -> IO IODeviceType
 120
 121   -- | duplicates the device, if possible.  The new device is expected
 122   -- to share a file pointer with the original device (like Unix @dup@).
 123   dup :: a -> IO a
 124   dup _ = ioe_unsupportedOperation
 125
 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
 131
 132 ioe_unsupportedOperation :: IO a
 133 ioe_unsupportedOperation = throwIO unsupportedOperation
 134
 135 -- | Type of a device that can be used to back a
 136 -- 'GHC.IO.Handle.Handle' (see also 'GHC.IO.Handle.mkFileHandle'). The
 137 -- standard libraries provide creation of 'GHC.IO.Handle.Handle's via
 138 -- Posix file operations with file descriptors (see
 139 -- 'GHC.IO.Handle.FD.mkHandleFromFD') with FD being the underlying
 140 -- 'GHC.IO.Device.IODevice' instance.
 141 --
 142 -- Users may provide custom instances of 'GHC.IO.Device.IODevice'
 143 -- which are expected to conform the following rules:
 144
 145 data IODeviceType
 146   = Directory -- ^ The standard libraries do not have direct support
 147               -- for this device type, but a user implementation is
 148               -- expected to provide a list of file names in
 149               -- the directory, in any order, separated by @'\0'@
 150               -- characters, excluding the @"."@ and @".."@ names. See
 151               -- also 'System.Directory.getDirectoryContents'.  Seek
 152               -- operations are not supported on directories (other
 153               -- than to the zero position).
 154   | Stream    -- ^ A duplex communications channel (results in
 155               -- creation of a duplex 'GHC.IO.Handle.Handle'). The
 156               -- standard libraries use this device type when
 157               -- creating 'GHC.IO.Handle.Handle's for open sockets.
 158   | RegularFile -- ^ A file that may be read or written, and also
 159                 -- may be seekable.
 160   | RawDevice -- ^ A "raw" (disk) device which supports block binary
 161               -- read and write operations and may be seekable only
 162               -- to positions of certain granularity (block-
 163               -- aligned).
 164   deriving (Eq)
 165
 166 -- -----------------------------------------------------------------------------
 167 -- SeekMode type
 168
 169 -- | A mode that determines the effect of 'hSeek' @hdl mode i@.
 170 data SeekMode
 171   = AbsoluteSeek        -- ^ the position of @hdl@ is set to @i@.
 172   | RelativeSeek        -- ^ the position of @hdl@ is set to offset @i@
 173                         -- from the current position.
 174   | SeekFromEnd         -- ^ the position of @hdl@ is set to offset @i@
 175                         -- from the end of the file.
 176     deriving (Eq, Ord, Ix, Enum, Read, Show)