{-# LANGUAGE Trustworthy #-} {-# LANGUAGE NoImplicitPrelude #-} ----------------------------------------------------------------------------- -- | -- Module : GHC.Internal.IO.Device -- Copyright : (c) The University of Glasgow, 1994-2008 -- License : see libraries/base/LICENSE -- -- Maintainer : libraries@haskell.org -- Stability : internal -- Portability : non-portable -- -- Type classes for I/O providers. -- -- /The API of this module is unstable and not meant to be consumed by the general public./ -- If you absolutely must depend on it, make sure to use a tight upper -- bound, e.g., @base < 4.X@ rather than @base < 5@, because the interface can -- change rapidly without much warning. -- ----------------------------------------------------------------------------- module GHC.Internal.IO.Device ( RawIO(..), IODevice(..), IODeviceType(..), SeekMode(..) ) where import GHC.Internal.Base import GHC.Internal.Word import GHC.Internal.Arr import GHC.Internal.Enum import GHC.Internal.Read import GHC.Internal.Show import GHC.Internal.Ptr import GHC.Internal.Num import GHC.Internal.IO import {-# SOURCE #-} GHC.Internal.IO.Exception ( unsupportedOperation ) -- | A low-level I/O provider where the data is bytes in memory. -- The Word64 offsets currently have no effect on POSIX system or consoles -- where the implicit behaviour of the C runtime is assumed to move the file -- pointer on every read/write without needing an explicit seek. class RawIO a where -- | Read up to the specified number of bytes starting from a specified -- offset, returning the number of bytes actually read. This function -- should only block if there is no data available. If there is not enough -- data available, then the function should just return the available data. -- A return value of zero indicates that the end of the data stream (e.g. end -- of file) has been reached. read :: a -> Ptr Word8 -> Word64 -> Int -> IO Int -- | Read up to the specified number of bytes starting from a specified -- offset, returning the number of bytes actually read, or 'Nothing' if -- the end of the stream has been reached. readNonBlocking :: a -> Ptr Word8 -> Word64 -> Int -> IO (Maybe Int) -- | Write the specified number of bytes starting at a given offset. write :: a -> Ptr Word8 -> Word64 -> Int -> IO () -- | Write up to the specified number of bytes without blocking starting at a -- given offset. Returns the actual number of bytes written. writeNonBlocking :: a -> Ptr Word8 -> Word64 -> Int -> IO Int -- | I/O operations required for implementing a 'System.IO.Handle'. class IODevice a where -- | @ready dev write msecs@ returns 'True' if the device has data -- to read (if @write@ is 'False') or space to write new data (if -- @write@ is 'True'). @msecs@ specifies how long to wait, in -- milliseconds. -- ready :: a -> Bool -> Int -> IO Bool -- | closes the device. Further operations on the device should -- produce exceptions. close :: a -> IO () -- | returns 'True' if the device is a terminal or console. isTerminal :: a -> IO Bool isTerminal _ = return False -- | returns 'True' if the device supports 'seek' operations. isSeekable :: a -> IO Bool isSeekable _ = return False -- | seek to the specified position in the data. seek :: a -> SeekMode -> Integer -> IO Integer seek _ _ _ = ioe_unsupportedOperation -- | return the current position in the data. tell :: a -> IO Integer tell _ = ioe_unsupportedOperation -- | return the size of the data. getSize :: a -> IO Integer getSize _ = ioe_unsupportedOperation -- | change the size of the data. setSize :: a -> Integer -> IO () setSize _ _ = ioe_unsupportedOperation -- | for terminal devices, changes whether characters are echoed on -- the device. setEcho :: a -> Bool -> IO () setEcho _ _ = ioe_unsupportedOperation -- | returns the current echoing status. getEcho :: a -> IO Bool getEcho _ = ioe_unsupportedOperation -- | some devices (e.g. terminals) support a "raw" mode where -- characters entered are immediately made available to the program. -- If available, this operation enables raw mode. setRaw :: a -> Bool -> IO () setRaw _ _ = ioe_unsupportedOperation -- | returns the 'IODeviceType' corresponding to this device. devType :: a -> IO IODeviceType -- | duplicates the device, if possible. The new device is expected -- to share a file pointer with the original device (like Unix @dup@). dup :: a -> IO a dup _ = ioe_unsupportedOperation -- | @dup2 source target@ replaces the target device with the source -- device. The target device is closed first, if necessary, and then -- it is made into a duplicate of the first device (like Unix @dup2@). dup2 :: a -> a -> IO a dup2 _ _ = ioe_unsupportedOperation ioe_unsupportedOperation :: IO a ioe_unsupportedOperation = throwIO unsupportedOperation -- | Type of a device that can be used to back a -- 'GHC.IO.Handle.Handle' (see also 'GHC.Internal.IO.Handle.mkFileHandle'). The -- standard libraries provide creation of 'GHC.IO.Handle.Handle's via -- Posix file operations with file descriptors (see -- 'GHC.Internal.IO.Handle.FD.mkHandleFromFD') with FD being the underlying -- 'GHC.IO.Device.IODevice' instance. -- -- Users may provide custom instances of 'GHC.IO.Device.IODevice' -- which are expected to conform the following rules: data IODeviceType = Directory -- ^ The standard libraries do not have direct support -- for this device type, but a user implementation is -- expected to provide a list of file names in -- the directory, in any order, separated by @\'\\0\'@ -- characters, excluding the @"."@ and @".."@ names. See -- also 'System.Directory.getDirectoryContents'. Seek -- operations are not supported on directories (other -- than to the zero position). | Stream -- ^ A duplex communications channel (results in -- creation of a duplex 'GHC.IO.Handle.Handle'). The -- standard libraries use this device type when -- creating 'GHC.IO.Handle.Handle's for open sockets. | RegularFile -- ^ A file that may be read or written, and also -- may be seekable. | RawDevice -- ^ A "raw" (disk) device which supports block binary -- read and write operations and may be seekable only -- to positions of certain granularity (block- -- aligned). deriving ( Eq -- ^ @since base-4.2.0.0 ) -- ----------------------------------------------------------------------------- -- SeekMode type -- | A mode that determines the effect of 'GHC.Internal.System.IO.hSeek' @hdl mode i@. data SeekMode = AbsoluteSeek -- ^ the position of @hdl@ is set to @i@. | RelativeSeek -- ^ the position of @hdl@ is set to offset @i@ -- from the current position. | SeekFromEnd -- ^ the position of @hdl@ is set to offset @i@ -- from the end of the file. deriving ( Eq -- ^ @since base-4.2.0.0 , Ord -- ^ @since base-4.2.0.0 , Ix -- ^ @since base-4.2.0.0 , Enum -- ^ @since base-4.2.0.0 , Read -- ^ @since base-4.2.0.0 , Show -- ^ @since base-4.2.0.0 )