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