Commit 23e89144 authored by Simon Marlow's avatar Simon Marlow

doc updates in System.IO

parent 035b6276
......@@ -142,7 +142,7 @@ data IODeviceType
-- -----------------------------------------------------------------------------
-- 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@
......
......@@ -393,6 +393,8 @@ hSetPosn (HandlePosn h i) = hSeek h AbsoluteSeek i
--
-- This operation may fail with:
--
-- * 'isIllegalOperationError' if the Handle is not seekable, or does
-- not support the requested seek mode.
-- * 'isPermissionError' if a system resource limit would be exceeded.
hSeek :: Handle -> SeekMode -> Integer -> IO ()
......@@ -417,6 +419,15 @@ hSeek handle mode offset =
IODevice.seek haDevice mode offset
-- | Computation 'hTell' @hdl@ returns the current position of the
-- handle @hdl@, as the number of bytes from the beginning of
-- the file. The value returned may be subsequently passed to
-- 'hSeek' to reposition the handle to the current position.
--
-- This operation may fail with:
--
-- * 'isIllegalOperationError' if the Handle is not seekable.
--
hTell :: Handle -> IO Integer
hTell handle =
wantSeekableHandle "hGetPosn" handle $ \ handle_@Handle__{..} -> do
......
......@@ -86,15 +86,6 @@ import Data.Typeable
-- enough information to identify the handle for debugging. A handle is
-- equal according to '==' only to itself; no attempt
-- is made to compare the internal state of different handles for equality.
--
-- GHC note: a 'Handle' will be automatically closed when the garbage
-- collector detects that it has become unreferenced by the program.
-- However, relying on this behaviour is not generally recommended:
-- the garbage collector is unpredictable. If possible, use explicit
-- an explicit 'hClose' to close 'Handle's when they are no longer
-- required. GHC does not currently attempt to free up file
-- descriptors when they have run out, it is your responsibility to
-- ensure that this doesn't happen.
data Handle
= FileHandle -- A normal handle to a file
......
......@@ -22,5 +22,6 @@ import GHC.Read
import GHC.Arr
import GHC.Enum
-- | See 'System.IO.openFile'
data IOMode = ReadMode | WriteMode | AppendMode | ReadWriteMode
deriving (Eq, Ord, Ix, Enum, Read, Show)
......@@ -25,6 +25,15 @@ module System.IO (
Handle, -- abstract, instance of: Eq, Show.
-- | GHC note: a 'Handle' will be automatically closed when the garbage
-- collector detects that it has become unreferenced by the program.
-- However, relying on this behaviour is not generally recommended:
-- the garbage collector is unpredictable. If possible, use explicit
-- an explicit 'hClose' to close 'Handle's when they are no longer
-- required. GHC does not currently attempt to free up file
-- descriptors when they have run out, it is your responsibility to
-- ensure that this doesn't happen.
-- ** Standard handles
-- | Three handles are allocated during program initialisation,
......@@ -615,8 +624,7 @@ foreign import ccall "getpid" c_getpid :: IO Int
-- $locking
-- Implementations should enforce as far as possible, at least locally to the
-- Haskell process, multiple-reader single-writer locking on files.
-- That is, /there may either be many handles on the same file which manage
-- input, or just one handle on the file which manages output/. If any
-- That is, /there may either be many handles on the same file which manage input, or just one handle on the file which manages output/. If any
-- open or semi-closed handle is managing a file for output, no new
-- handle can be allocated for that file. If any open or semi-closed
-- handle is managing a file for input, new handles can only be allocated
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment