documentation for IODeviceType (#4317, edited by me)

[ghc-base.git] / GHC / IO / Device.hs

diff --git a/GHC/IO/Device.hs b/GHC/IO/Device.hs
index ab91bc0..d1a6712 100644 (file)
--- a/GHC/IO/Device.hs
+++ b/GHC/IO/Device.hs
@@ -1,5 +1,4 @@
 {-# OPTIONS_GHC -XNoImplicitPrelude -XBangPatterns #-}
-{-# OPTIONS_HADDOCK hide #-}
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  GHC.IO.Device
@@ -21,6 +20,7 @@ module GHC.IO.Device (
     SeekMode(..)
   ) where  
 
+#ifdef __GLASGOW_HASKELL__
 import GHC.Base
 import GHC.Word
 import GHC.Arr
@@ -32,6 +32,13 @@ import Data.Maybe
 import GHC.Num
 import GHC.IO
 import {-# SOURCE #-} GHC.IO.Exception ( unsupportedOperation )
+#endif
+#ifdef __NHC__
+import Foreign
+import Ix
+import Control.Exception.Base
+unsupportedOperation = userError "unsupported operation"
+#endif
 
 -- | A low-level I/O provider where the data is bytes in memory.
 class RawIO a where
@@ -77,7 +84,7 @@ class IODevice a where
   isSeekable :: a -> IO Bool
   isSeekable _ = return False
 
-  -- | seek to the specified positing in the data.
+  -- | seek to the specified position in the data.
   seek :: a -> SeekMode -> Integer -> IO ()
   seek _ _ _ = ioe_unsupportedOperation
 
@@ -125,17 +132,42 @@ class IODevice a where
 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.IO.Handle.mkFileHandle'). The
+-- standard libraries provide creation of 'GHC.IO.Handle.Handle's via
+-- Posix file operations with file descriptors (see
+-- 'GHC.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
-  | Stream
-  | RegularFile
-  | RawDevice
+  = Directory -- ^ The standard libraries do not have direct support
+              -- for this device type, but user implementation is
+              -- expected to provide a newline-separated list of
+              -- file names in a directory (without path to the
+              -- directory itself) in any order,
+              -- 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)
 
 -- -----------------------------------------------------------------------------
 -- SeekMode type
 
--- | A mode that determines the effect of 'hSeek' @hdl mode i@, as follows:
+-- | A mode that determines the effect of '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@