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