GHC/IO/Handle/FD.hs

   1 {-# OPTIONS_GHC -XNoImplicitPrelude #-}
   2 -----------------------------------------------------------------------------
   3 -- |
   4 -- Module      :  GHC.IO.Handle.FD
   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 -- Handle operations implemented by file descriptors (FDs)
  13 --
  14 -----------------------------------------------------------------------------
  15
  16 module GHC.IO.Handle.FD (
  17   stdin, stdout, stderr,
  18   openFile, openBinaryFile,
  19   mkHandleFromFD, fdToHandle, fdToHandle',
  20   isEOF
  21  ) where
  22
  23 import GHC.Base
  24 import GHC.Num
  25 import GHC.Real
  26 import GHC.Show
  27 import Data.Maybe
  28 import Control.Monad
  29 import Foreign.C.Types
  30 import GHC.MVar
  31 import GHC.IO
  32 import GHC.IO.Encoding
  33 import GHC.IO.Exception
  34 import GHC.IO.Device as IODevice
  35 import GHC.IO.Exception
  36 import GHC.IO.IOMode
  37 import GHC.IO.Handle
  38 import GHC.IO.Handle.Types
  39 import GHC.IO.Handle.Internals
  40 import GHC.IO.FD (FD(..))
  41 import qualified GHC.IO.FD as FD
  42 import qualified System.Posix.Internals as Posix
  43
  44 -- ---------------------------------------------------------------------------
  45 -- Standard Handles
  46
  47 -- Three handles are allocated during program initialisation.  The first
  48 -- two manage input or output from the Haskell program's standard input
  49 -- or output channel respectively.  The third manages output to the
  50 -- standard error channel. These handles are initially open.
  51
  52 -- | A handle managing input from the Haskell program's standard input channel.
  53 stdin :: Handle
  54 stdin = unsafePerformIO $ do
  55    -- ToDo: acquire lock
  56    mkHandle FD.stdin "<stdin>" ReadHandle True (Just localeEncoding)
  57                 nativeNewlineMode{-translate newlines-}
  58                 (Just stdHandleFinalizer) Nothing
  59
  60 -- | A handle managing output to the Haskell program's standard output channel.
  61 stdout :: Handle
  62 stdout = unsafePerformIO $ do
  63    -- ToDo: acquire lock
  64    mkHandle FD.stdout "<stdout>" WriteHandle True (Just localeEncoding)
  65                 nativeNewlineMode{-translate newlines-}
  66                 (Just stdHandleFinalizer) Nothing
  67
  68 -- | A handle managing output to the Haskell program's standard error channel.
  69 stderr :: Handle
  70 stderr = unsafePerformIO $ do
  71     -- ToDo: acquire lock
  72    mkHandle FD.stderr "<stderr>" WriteHandle False{-stderr is unbuffered-}
  73                 (Just localeEncoding)
  74                 nativeNewlineMode{-translate newlines-}
  75                 (Just stdHandleFinalizer) Nothing
  76
  77 stdHandleFinalizer :: FilePath -> MVar Handle__ -> IO ()
  78 stdHandleFinalizer fp m = do
  79   h_ <- takeMVar m
  80   flushWriteBuffer h_
  81   putMVar m (ioe_finalizedHandle fp)
  82
  83 -- ---------------------------------------------------------------------------
  84 -- isEOF
  85
  86 -- | The computation 'isEOF' is identical to 'hIsEOF',
  87 -- except that it works only on 'stdin'.
  88
  89 isEOF :: IO Bool
  90 isEOF = hIsEOF stdin
  91
  92 -- ---------------------------------------------------------------------------
  93 -- Opening and Closing Files
  94
  95 addFilePathToIOError :: String -> FilePath -> IOException -> IOException
  96 addFilePathToIOError fun fp ioe
  97   = ioe{ ioe_location = fun, ioe_filename = Just fp }
  98
  99 -- | Computation 'openFile' @file mode@ allocates and returns a new, open
 100 -- handle to manage the file @file@.  It manages input if @mode@
 101 -- is 'ReadMode', output if @mode@ is 'WriteMode' or 'AppendMode',
 102 -- and both input and output if mode is 'ReadWriteMode'.
 103 --
 104 -- If the file does not exist and it is opened for output, it should be
 105 -- created as a new file.  If @mode@ is 'WriteMode' and the file
 106 -- already exists, then it should be truncated to zero length.
 107 -- Some operating systems delete empty files, so there is no guarantee
 108 -- that the file will exist following an 'openFile' with @mode@
 109 -- 'WriteMode' unless it is subsequently written to successfully.
 110 -- The handle is positioned at the end of the file if @mode@ is
 111 -- 'AppendMode', and otherwise at the beginning (in which case its
 112 -- internal position is 0).
 113 -- The initial buffer mode is implementation-dependent.
 114 --
 115 -- This operation may fail with:
 116 --
 117 --  * 'isAlreadyInUseError' if the file is already open and cannot be reopened;
 118 --
 119 --  * 'isDoesNotExistError' if the file does not exist; or
 120 --
 121 --  * 'isPermissionError' if the user does not have permission to open the file.
 122 --
 123 -- Note: if you will be working with files containing binary data, you'll want to
 124 -- be using 'openBinaryFile'.
 125 openFile :: FilePath -> IOMode -> IO Handle
 126 openFile fp im =
 127   catchException
 128     (openFile' fp im dEFAULT_OPEN_IN_BINARY_MODE)
 129     (\e -> ioError (addFilePathToIOError "openFile" fp e))
 130
 131 -- | Like 'openFile', but open the file in binary mode.
 132 -- On Windows, reading a file in text mode (which is the default)
 133 -- will translate CRLF to LF, and writing will translate LF to CRLF.
 134 -- This is usually what you want with text files.  With binary files
 135 -- this is undesirable; also, as usual under Microsoft operating systems,
 136 -- text mode treats control-Z as EOF.  Binary mode turns off all special
 137 -- treatment of end-of-line and end-of-file characters.
 138 -- (See also 'hSetBinaryMode'.)
 139
 140 openBinaryFile :: FilePath -> IOMode -> IO Handle
 141 openBinaryFile fp m =
 142   catchException
 143     (openFile' fp m True)
 144     (\e -> ioError (addFilePathToIOError "openBinaryFile" fp e))
 145
 146 openFile' :: String -> IOMode -> Bool -> IO Handle
 147 openFile' filepath iomode binary = do
 148   -- first open the file to get an FD
 149   (fd, fd_type) <- FD.openFile filepath iomode
 150
 151   let mb_codec = if binary then Nothing else Just localeEncoding
 152
 153   -- then use it to make a Handle
 154   mkHandleFromFD fd fd_type filepath iomode True{-non-blocking-} mb_codec
 155             `onException` IODevice.close fd
 156         -- NB. don't forget to close the FD if mkHandleFromFD fails, otherwise
 157         -- this FD leaks.
 158         -- ASSERT: if we just created the file, then fdToHandle' won't fail
 159         -- (so we don't need to worry about removing the newly created file
 160         --  in the event of an error).
 161
 162
 163 -- ---------------------------------------------------------------------------
 164 -- Converting file descriptors to Handles
 165
 166 mkHandleFromFD
 167    :: FD
 168    -> IODeviceType
 169    -> FilePath -- a string describing this file descriptor (e.g. the filename)
 170    -> IOMode
 171    -> Bool -- non_blocking (*sets* non-blocking mode on the FD)
 172    -> Maybe TextEncoding
 173    -> IO Handle
 174
 175 mkHandleFromFD fd0 fd_type filepath iomode set_non_blocking mb_codec
 176   = do
 177 #ifndef mingw32_HOST_OS
 178     -- turn on non-blocking mode
 179     fd <- if set_non_blocking
 180              then FD.setNonBlockingMode fd0 True
 181              else return fd0
 182 #else
 183     let _ = set_non_blocking -- warning suppression
 184     fd <- return fd0
 185 #endif
 186
 187     let nl | isJust mb_codec = nativeNewlineMode
 188            | otherwise       = noNewlineTranslation
 189
 190     case fd_type of
 191         Directory ->
 192            ioException (IOError Nothing InappropriateType "openFile"
 193                            "is a directory" Nothing Nothing)
 194
 195         Stream
 196            -- only *Streams* can be DuplexHandles.  Other read/write
 197            -- Handles must share a buffer.
 198            | ReadWriteMode <- iomode ->
 199                 mkDuplexHandle fd filepath mb_codec nl
 200
 201
 202         _other ->
 203            mkFileHandle fd filepath iomode mb_codec nl
 204
 205 -- | Old API kept to avoid breaking clients
 206 fdToHandle' :: CInt
 207             -> Maybe IODeviceType
 208             -> Bool -- is_socket on Win, non-blocking on Unix
 209             -> FilePath
 210             -> IOMode
 211             -> Bool -- binary
 212             -> IO Handle
 213 fdToHandle' fdint mb_type is_socket filepath iomode binary = do
 214   let mb_stat = case mb_type of
 215                         Nothing          -> Nothing
 216                           -- mkFD will do the stat:
 217                         Just RegularFile -> Nothing
 218                           -- no stat required for streams etc.:
 219                         Just other       -> Just (other,0,0)
 220   (fd,fd_type) <- FD.mkFD (fromIntegral fdint) iomode mb_stat
 221                        is_socket
 222                        is_socket
 223   mkHandleFromFD fd fd_type filepath iomode is_socket
 224                        (if binary then Nothing else Just localeEncoding)
 225
 226
 227 -- | Turn an existing file descriptor into a Handle.  This is used by
 228 -- various external libraries to make Handles.
 229 --
 230 -- Makes a binary Handle.  This is for historical reasons; it should
 231 -- probably be a text Handle with the default encoding and newline
 232 -- translation instead.
 233 fdToHandle :: Posix.FD -> IO Handle
 234 fdToHandle fdint = do
 235    iomode <- Posix.fdGetMode (fromIntegral fdint)
 236    (fd,fd_type) <- FD.mkFD (fromIntegral fdint) iomode Nothing
 237             False{-is_socket-}
 238               -- NB. the is_socket flag is False, meaning that:
 239               --  on Windows we're guessing this is not a socket (XXX)
 240             False{-is_nonblock-}
 241               -- file descriptors that we get from external sources are
 242               -- not put into non-blocking mode, becuase that would affect
 243               -- other users of the file descriptor
 244    let fd_str = "<file descriptor: " ++ show fd ++ ">"
 245    mkHandleFromFD fd fd_type fd_str iomode False{-non-block-}
 246                   Nothing -- bin mode
 247
 248 -- ---------------------------------------------------------------------------
 249 -- Are files opened by default in text or binary mode, if the user doesn't
 250 -- specify?
 251
 252 dEFAULT_OPEN_IN_BINARY_MODE :: Bool
 253 dEFAULT_OPEN_IN_BINARY_MODE = False