IO.hs

{-# LANGUAGE Safe #-}

-- |
--
-- Module      :  System.IO
-- Copyright   :  (c) The University of Glasgow 2001
-- License     :  BSD-style (see the file libraries/base/LICENSE)
--
-- Maintainer  :  libraries@haskell.org
-- Stability   :  stable
-- Portability :  portable
--
-- The standard IO API.
--

module System.IO
    (-- * Examples
     -- $stdio_examples

     -- *  The IO monad
     IO,
     fixIO,
     -- *  Files and handles
     FilePath,
     Handle,
     -- |  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
     -- 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,
     -- and are initially open.
     stdin,
     stdout,
     stderr,
     -- *  Opening and closing files
     -- **  Opening files
     withFile,
     openFile,
     IOMode(ReadMode, WriteMode, AppendMode, ReadWriteMode),
     -- **  Closing files
     hClose,
     -- **  Special cases
     -- |  These functions are also exported by the "Prelude".
     readFile,
     readFile',
     writeFile,
     appendFile,
     -- **  File locking
     -- $locking
     -- *  Operations on handles
     -- **  Determining and changing the size of a file
     hFileSize,
     hSetFileSize,
     -- **  Detecting the end of input
     hIsEOF,
     isEOF,
     -- **  Buffering operations
     BufferMode(NoBuffering, LineBuffering, BlockBuffering),
     hSetBuffering,
     hGetBuffering,
     hFlush,
     -- **  Repositioning handles
     hGetPosn,
     hSetPosn,
     HandlePosn,
     hSeek,
     SeekMode(AbsoluteSeek, RelativeSeek, SeekFromEnd),
     hTell,
     -- **  Handle properties
     hIsOpen,
     hIsClosed,
     hIsReadable,
     hIsWritable,
     hIsSeekable,
     -- **  Terminal operations (not portable: GHC only)
     hIsTerminalDevice,
     hSetEcho,
     hGetEcho,
     -- **  Showing handle state (not portable: GHC only)
     hShow,
     -- *  Text input and output
     -- **  Text input
     hWaitForInput,
     hReady,
     hGetChar,
     hGetLine,
     hLookAhead,
     hGetContents,
     hGetContents',
     -- **  Text output
     hPutChar,
     hPutStr,
     hPutStrLn,
     hPrint,
     -- **  Special cases for standard input and output
     -- |  These functions are also exported by the "Prelude".
     interact,
     putChar,
     putStr,
     putStrLn,
     print,
     getChar,
     getLine,
     getContents,
     getContents',
     readIO,
     readLn,
     -- *  Binary input and output
     withBinaryFile,
     openBinaryFile,
     hSetBinaryMode,
     hPutBuf,
     hGetBuf,
     hGetBufSome,
     hPutBufNonBlocking,
     hGetBufNonBlocking,
     -- *  Temporary files
     openTempFile,
     openBinaryTempFile,
     openTempFileWithDefaultPermissions,
     openBinaryTempFileWithDefaultPermissions,
     -- *  Unicode encoding\/decoding
     -- |  A text-mode 'Handle' has an associated 'TextEncoding', which
     -- is used to decode bytes into Unicode characters when reading,
     -- and encode Unicode characters into bytes when writing.
     --
     -- The default 'TextEncoding' is the same as the default encoding
     -- on your system, which is also available as 'localeEncoding'.
     -- (GHC note: on Windows, we currently do not support double-byte
     -- encodings; if the console\'s code page is unsupported, then
     -- 'localeEncoding' will be 'latin1'.)
     --
     -- Encoding and decoding errors are always detected and reported,
     -- except during lazy I/O ('hGetContents', 'getContents', and
     -- 'readFile'), where a decoding error merely results in
     -- termination of the character stream, as with other I/O errors.
     hSetEncoding,
     hGetEncoding,
     -- **  Unicode encodings
     TextEncoding,
     latin1,
     utf8,
     utf8_bom,
     utf16,
     utf16le,
     utf16be,
     utf32,
     utf32le,
     utf32be,
     localeEncoding,
     char8,
     mkTextEncoding,
     -- *  Newline conversion
     -- | In Haskell, a newline is always represented by the character
     -- @\'\\n\'@.  However, in files and external character streams, a
     -- newline may be represented by another character sequence, such
     -- as @\'\\r\\n\'@.
     --
     -- A text-mode 'Handle' has an associated 'NewlineMode' that
     -- specifies how to translate newline characters.  The
     -- 'NewlineMode' specifies the input and output translation
     -- separately, so that for instance you can translate @\'\\r\\n\'@
     -- to @\'\\n\'@ on input, but leave newlines as @\'\\n\'@ on output.
     --
     -- The default 'NewlineMode' for a 'Handle' is
     -- 'nativeNewlineMode', which does no translation on Unix systems,
     -- but translates @\'\\r\\n\'@ to @\'\\n\'@ and back on Windows.
     --
     -- Binary-mode 'Handle's do no newline translation at all.

     hSetNewlineMode,
     Newline(..),
     nativeNewline,
     NewlineMode(..),
     noNewlineTranslation,
     universalNewlineMode,
     nativeNewlineMode
     ) where

import GHC.Internal.System.IO

-- $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
-- 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
-- if they do not manage output.  Whether two files are the same is
-- implementation-dependent, but they should normally be the same if they
-- have the same absolute path name and neither has been renamed, for
-- example.
--
-- /Warning/: the 'readFile' operation holds a semi-closed handle on
-- the file until the entire contents of the file have been consumed.
-- It follows that an attempt to write to a file (using 'writeFile', for
-- example) that was earlier opened by 'readFile' will usually result in
-- failure with 'GHC.Internal.System.IO.Error.isAlreadyInUseError'.

-- $stdio_examples
-- Note: Some of the examples in this module do not work "as is" in ghci.
-- This is because using 'stdin' in combination with lazy IO
-- does not work well in interactive mode.
--
-- Lines starting with @>@ indicate 'stdin' and @^D@ signales EOF.
--
-- ==== __Example__
--
-- ghci> foo
-- > input
-- output
-- > input^D
-- output