Fix Windows build.
[packages/base.git] / System / IO.hs
1 {-# LANGUAGE Trustworthy #-}
2 {-# LANGUAGE CPP, NoImplicitPrelude #-}
3
4 -----------------------------------------------------------------------------
5 -- |
6 -- Module : System.IO
7 -- Copyright : (c) The University of Glasgow 2001
8 -- License : BSD-style (see the file libraries/base/LICENSE)
9 --
10 -- Maintainer : libraries@haskell.org
11 -- Stability : stable
12 -- Portability : portable
13 --
14 -- The standard IO library.
15 --
16 -----------------------------------------------------------------------------
17
18 module System.IO (
19 -- * The IO monad
20
21 IO,
22 fixIO,
23
24 -- * Files and handles
25
26 FilePath,
27
28 Handle, -- abstract, instance of: Eq, Show.
29
30 -- | GHC note: a 'Handle' will be automatically closed when the garbage
31 -- collector detects that it has become unreferenced by the program.
32 -- However, relying on this behaviour is not generally recommended:
33 -- the garbage collector is unpredictable. If possible, use
34 -- an explicit 'hClose' to close 'Handle's when they are no longer
35 -- required. GHC does not currently attempt to free up file
36 -- descriptors when they have run out, it is your responsibility to
37 -- ensure that this doesn't happen.
38
39 -- ** Standard handles
40
41 -- | Three handles are allocated during program initialisation,
42 -- and are initially open.
43
44 stdin, stdout, stderr,
45
46 -- * Opening and closing files
47
48 -- ** Opening files
49
50 withFile,
51 openFile,
52 IOMode(ReadMode,WriteMode,AppendMode,ReadWriteMode),
53
54 -- ** Closing files
55
56 hClose,
57
58 -- ** Special cases
59
60 -- | These functions are also exported by the "Prelude".
61
62 readFile,
63 writeFile,
64 appendFile,
65
66 -- ** File locking
67
68 -- $locking
69
70 -- * Operations on handles
71
72 -- ** Determining and changing the size of a file
73
74 hFileSize,
75 hSetFileSize,
76
77 -- ** Detecting the end of input
78
79 hIsEOF,
80 isEOF,
81
82 -- ** Buffering operations
83
84 BufferMode(NoBuffering,LineBuffering,BlockBuffering),
85 hSetBuffering,
86 hGetBuffering,
87 hFlush,
88
89 -- ** Repositioning handles
90
91 hGetPosn,
92 hSetPosn,
93 HandlePosn, -- abstract, instance of: Eq, Show.
94
95 hSeek,
96 SeekMode(AbsoluteSeek,RelativeSeek,SeekFromEnd),
97 hTell,
98
99 -- ** Handle properties
100
101 hIsOpen, hIsClosed,
102 hIsReadable, hIsWritable,
103 hIsSeekable,
104
105 -- ** Terminal operations (not portable: GHC only)
106
107 hIsTerminalDevice,
108
109 hSetEcho,
110 hGetEcho,
111
112 -- ** Showing handle state (not portable: GHC only)
113
114 hShow,
115
116 -- * Text input and output
117
118 -- ** Text input
119
120 hWaitForInput,
121 hReady,
122 hGetChar,
123 hGetLine,
124 hLookAhead,
125 hGetContents,
126
127 -- ** Text output
128
129 hPutChar,
130 hPutStr,
131 hPutStrLn,
132 hPrint,
133
134 -- ** Special cases for standard input and output
135
136 -- | These functions are also exported by the "Prelude".
137
138 interact,
139 putChar,
140 putStr,
141 putStrLn,
142 print,
143 getChar,
144 getLine,
145 getContents,
146 readIO,
147 readLn,
148
149 -- * Binary input and output
150
151 withBinaryFile,
152 openBinaryFile,
153 hSetBinaryMode,
154 hPutBuf,
155 hGetBuf,
156 hGetBufSome,
157 hPutBufNonBlocking,
158 hGetBufNonBlocking,
159
160 -- * Temporary files
161
162 openTempFile,
163 openBinaryTempFile,
164 openTempFileWithDefaultPermissions,
165 openBinaryTempFileWithDefaultPermissions,
166
167 -- * Unicode encoding\/decoding
168
169 -- | A text-mode 'Handle' has an associated 'TextEncoding', which
170 -- is used to decode bytes into Unicode characters when reading,
171 -- and encode Unicode characters into bytes when writing.
172 --
173 -- The default 'TextEncoding' is the same as the default encoding
174 -- on your system, which is also available as 'localeEncoding'.
175 -- (GHC note: on Windows, we currently do not support double-byte
176 -- encodings; if the console\'s code page is unsupported, then
177 -- 'localeEncoding' will be 'latin1'.)
178 --
179 -- Encoding and decoding errors are always detected and reported,
180 -- except during lazy I/O ('hGetContents', 'getContents', and
181 -- 'readFile'), where a decoding error merely results in
182 -- termination of the character stream, as with other I/O errors.
183
184 hSetEncoding,
185 hGetEncoding,
186
187 -- ** Unicode encodings
188 TextEncoding,
189 latin1,
190 utf8, utf8_bom,
191 utf16, utf16le, utf16be,
192 utf32, utf32le, utf32be,
193 localeEncoding,
194 char8,
195 mkTextEncoding,
196
197 -- * Newline conversion
198
199 -- | In Haskell, a newline is always represented by the character
200 -- '\n'. However, in files and external character streams, a
201 -- newline may be represented by another character sequence, such
202 -- as '\r\n'.
203 --
204 -- A text-mode 'Handle' has an associated 'NewlineMode' that
205 -- specifies how to transate newline characters. The
206 -- 'NewlineMode' specifies the input and output translation
207 -- separately, so that for instance you can translate '\r\n'
208 -- to '\n' on input, but leave newlines as '\n' on output.
209 --
210 -- The default 'NewlineMode' for a 'Handle' is
211 -- 'nativeNewlineMode', which does no translation on Unix systems,
212 -- but translates '\r\n' to '\n' and back on Windows.
213 --
214 -- Binary-mode 'Handle's do no newline translation at all.
215 --
216 hSetNewlineMode,
217 Newline(..), nativeNewline,
218 NewlineMode(..),
219 noNewlineTranslation, universalNewlineMode, nativeNewlineMode,
220 ) where
221
222 import Control.Exception.Base
223
224 import Data.Bits
225 import Data.List
226 import Data.Maybe
227 import Foreign.C.Error
228 #ifdef mingw32_HOST_OS
229 import Foreign.C.String
230 #endif
231 import Foreign.C.Types
232 import System.Posix.Internals
233 import System.Posix.Types
234
235 import GHC.Base
236 import GHC.IO hiding ( bracket, onException )
237 import GHC.IO.IOMode
238 import GHC.IO.Handle.FD
239 import qualified GHC.IO.FD as FD
240 import GHC.IO.Handle
241 import GHC.IO.Handle.Text ( hGetBufSome, hPutStrLn )
242 import GHC.IO.Exception ( userError )
243 import GHC.IO.Encoding
244 import GHC.Num
245 import Text.Read
246 import GHC.Show
247 import GHC.MVar
248
249 -- -----------------------------------------------------------------------------
250 -- Standard IO
251
252 -- | Write a character to the standard output device
253 -- (same as 'hPutChar' 'stdout').
254
255 putChar :: Char -> IO ()
256 putChar c = hPutChar stdout c
257
258 -- | Write a string to the standard output device
259 -- (same as 'hPutStr' 'stdout').
260
261 putStr :: String -> IO ()
262 putStr s = hPutStr stdout s
263
264 -- | The same as 'putStr', but adds a newline character.
265
266 putStrLn :: String -> IO ()
267 putStrLn s = hPutStrLn stdout s
268
269 -- | The 'print' function outputs a value of any printable type to the
270 -- standard output device.
271 -- Printable types are those that are instances of class 'Show'; 'print'
272 -- converts values to strings for output using the 'show' operation and
273 -- adds a newline.
274 --
275 -- For example, a program to print the first 20 integers and their
276 -- powers of 2 could be written as:
277 --
278 -- > main = print ([(n, 2^n) | n <- [0..19]])
279
280 print :: Show a => a -> IO ()
281 print x = putStrLn (show x)
282
283 -- | Read a character from the standard input device
284 -- (same as 'hGetChar' 'stdin').
285
286 getChar :: IO Char
287 getChar = hGetChar stdin
288
289 -- | Read a line from the standard input device
290 -- (same as 'hGetLine' 'stdin').
291
292 getLine :: IO String
293 getLine = hGetLine stdin
294
295 -- | The 'getContents' operation returns all user input as a single string,
296 -- which is read lazily as it is needed
297 -- (same as 'hGetContents' 'stdin').
298
299 getContents :: IO String
300 getContents = hGetContents stdin
301
302 -- | The 'interact' function takes a function of type @String->String@
303 -- as its argument. The entire input from the standard input device is
304 -- passed to this function as its argument, and the resulting string is
305 -- output on the standard output device.
306
307 interact :: (String -> String) -> IO ()
308 interact f = do s <- getContents
309 putStr (f s)
310
311 -- | The 'readFile' function reads a file and
312 -- returns the contents of the file as a string.
313 -- The file is read lazily, on demand, as with 'getContents'.
314
315 readFile :: FilePath -> IO String
316 readFile name = openFile name ReadMode >>= hGetContents
317
318 -- | The computation 'writeFile' @file str@ function writes the string @str@,
319 -- to the file @file@.
320 writeFile :: FilePath -> String -> IO ()
321 writeFile f txt = withFile f WriteMode (\ hdl -> hPutStr hdl txt)
322
323 -- | The computation 'appendFile' @file str@ function appends the string @str@,
324 -- to the file @file@.
325 --
326 -- Note that 'writeFile' and 'appendFile' write a literal string
327 -- to a file. To write a value of any printable type, as with 'print',
328 -- use the 'show' function to convert the value to a string first.
329 --
330 -- > main = appendFile "squares" (show [(x,x*x) | x <- [0,0.1..2]])
331
332 appendFile :: FilePath -> String -> IO ()
333 appendFile f txt = withFile f AppendMode (\ hdl -> hPutStr hdl txt)
334
335 -- | The 'readLn' function combines 'getLine' and 'readIO'.
336
337 readLn :: Read a => IO a
338 readLn = do l <- getLine
339 r <- readIO l
340 return r
341
342 -- | The 'readIO' function is similar to 'read' except that it signals
343 -- parse failure to the 'IO' monad instead of terminating the program.
344
345 readIO :: Read a => String -> IO a
346 readIO s = case (do { (x,t) <- reads s ;
347 ("","") <- lex t ;
348 return x }) of
349 [x] -> return x
350 [] -> ioError (userError "Prelude.readIO: no parse")
351 _ -> ioError (userError "Prelude.readIO: ambiguous parse")
352
353 -- | The Unicode encoding of the current locale
354 --
355 -- This is the initial locale encoding: if it has been subsequently changed by
356 -- 'GHC.IO.Encoding.setLocaleEncoding' this value will not reflect that change.
357 localeEncoding :: TextEncoding
358 localeEncoding = initLocaleEncoding
359
360 -- | Computation 'hReady' @hdl@ indicates whether at least one item is
361 -- available for input from handle @hdl@.
362 --
363 -- This operation may fail with:
364 --
365 -- * 'System.IO.Error.isEOFError' if the end of file has been reached.
366
367 hReady :: Handle -> IO Bool
368 hReady h = hWaitForInput h 0
369
370 -- | Computation 'hPrint' @hdl t@ writes the string representation of @t@
371 -- given by the 'shows' function to the file or channel managed by @hdl@
372 -- and appends a newline.
373 --
374 -- This operation may fail with:
375 --
376 -- * 'System.IO.Error.isFullError' if the device is full; or
377 --
378 -- * 'System.IO.Error.isPermissionError' if another system resource limit would be exceeded.
379
380 hPrint :: Show a => Handle -> a -> IO ()
381 hPrint hdl = hPutStrLn hdl . show
382
383 -- | @'withFile' name mode act@ opens a file using 'openFile' and passes
384 -- the resulting handle to the computation @act@. The handle will be
385 -- closed on exit from 'withFile', whether by normal termination or by
386 -- raising an exception. If closing the handle raises an exception, then
387 -- this exception will be raised by 'withFile' rather than any exception
388 -- raised by 'act'.
389 withFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
390 withFile name mode = bracket (openFile name mode) hClose
391
392 -- | @'withBinaryFile' name mode act@ opens a file using 'openBinaryFile'
393 -- and passes the resulting handle to the computation @act@. The handle
394 -- will be closed on exit from 'withBinaryFile', whether by normal
395 -- termination or by raising an exception.
396 withBinaryFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
397 withBinaryFile name mode = bracket (openBinaryFile name mode) hClose
398
399 -- ---------------------------------------------------------------------------
400 -- fixIO
401
402 fixIO :: (a -> IO a) -> IO a
403 fixIO k = do
404 m <- newEmptyMVar
405 ans <- unsafeInterleaveIO (takeMVar m)
406 result <- k ans
407 putMVar m result
408 return result
409
410 -- NOTE: we do our own explicit black holing here, because GHC's lazy
411 -- blackholing isn't enough. In an infinite loop, GHC may run the IO
412 -- computation a few times before it notices the loop, which is wrong.
413 --
414 -- NOTE2: the explicit black-holing with an IORef ran into trouble
415 -- with multiple threads (see #5421), so now we use an MVar. I'm
416 -- actually wondering whether we should use readMVar rather than
417 -- takeMVar, just in case it ends up being executed multiple times,
418 -- but even then it would have to be masked to protect against async
419 -- exceptions. Ugh. What we really need here is an IVar, or an
420 -- atomic readMVar, or even STM. All these seem like overkill.
421 --
422 -- See also System.IO.Unsafe.unsafeFixIO.
423 --
424
425 -- | The function creates a temporary file in ReadWrite mode.
426 -- The created file isn\'t deleted automatically, so you need to delete it manually.
427 --
428 -- The file is creates with permissions such that only the current
429 -- user can read\/write it.
430 --
431 -- With some exceptions (see below), the file will be created securely
432 -- in the sense that an attacker should not be able to cause
433 -- openTempFile to overwrite another file on the filesystem using your
434 -- credentials, by putting symbolic links (on Unix) in the place where
435 -- the temporary file is to be created. On Unix the @O_CREAT@ and
436 -- @O_EXCL@ flags are used to prevent this attack, but note that
437 -- @O_EXCL@ is sometimes not supported on NFS filesystems, so if you
438 -- rely on this behaviour it is best to use local filesystems only.
439 --
440 openTempFile :: FilePath -- ^ Directory in which to create the file
441 -> String -- ^ File name template. If the template is \"foo.ext\" then
442 -- the created file will be \"fooXXX.ext\" where XXX is some
443 -- random number.
444 -> IO (FilePath, Handle)
445 openTempFile tmp_dir template
446 = openTempFile' "openTempFile" tmp_dir template False 0o600
447
448 -- | Like 'openTempFile', but opens the file in binary mode. See 'openBinaryFile' for more comments.
449 openBinaryTempFile :: FilePath -> String -> IO (FilePath, Handle)
450 openBinaryTempFile tmp_dir template
451 = openTempFile' "openBinaryTempFile" tmp_dir template True 0o600
452
453 -- | Like 'openTempFile', but uses the default file permissions
454 openTempFileWithDefaultPermissions :: FilePath -> String
455 -> IO (FilePath, Handle)
456 openTempFileWithDefaultPermissions tmp_dir template
457 = openTempFile' "openBinaryTempFile" tmp_dir template False 0o666
458
459 -- | Like 'openBinaryTempFile', but uses the default file permissions
460 openBinaryTempFileWithDefaultPermissions :: FilePath -> String
461 -> IO (FilePath, Handle)
462 openBinaryTempFileWithDefaultPermissions tmp_dir template
463 = openTempFile' "openBinaryTempFile" tmp_dir template True 0o666
464
465 openTempFile' :: String -> FilePath -> String -> Bool -> CMode
466 -> IO (FilePath, Handle)
467 openTempFile' loc tmp_dir template binary mode = do
468 pid <- c_getpid
469 findTempName pid
470 where
471 -- We split off the last extension, so we can use .foo.ext files
472 -- for temporary files (hidden on Unix OSes). Unfortunately we're
473 -- below filepath in the hierarchy here.
474 (prefix,suffix) =
475 case break (== '.') $ reverse template of
476 -- First case: template contains no '.'s. Just re-reverse it.
477 (rev_suffix, "") -> (reverse rev_suffix, "")
478 -- Second case: template contains at least one '.'. Strip the
479 -- dot from the prefix and prepend it to the suffix (if we don't
480 -- do this, the unique number will get added after the '.' and
481 -- thus be part of the extension, which is wrong.)
482 (rev_suffix, '.':rest) -> (reverse rest, '.':reverse rev_suffix)
483 -- Otherwise, something is wrong, because (break (== '.')) should
484 -- always return a pair with either the empty string or a string
485 -- beginning with '.' as the second component.
486 _ -> error "bug in System.IO.openTempFile"
487
488 findTempName x = do
489 r <- openNewFile filepath binary mode
490 case r of
491 FileExists -> findTempName (x + 1)
492 OpenNewError errno -> ioError (errnoToIOError loc errno Nothing (Just tmp_dir))
493 NewFileCreated fd -> do
494 (fD,fd_type) <- FD.mkFD fd ReadWriteMode Nothing{-no stat-}
495 False{-is_socket-}
496 True{-is_nonblock-}
497
498 enc <- getLocaleEncoding
499 h <- mkHandleFromFD fD fd_type filepath ReadWriteMode False{-set non-block-} (Just enc)
500
501 return (filepath, h)
502
503 where
504 filename = prefix ++ show x ++ suffix
505 filepath = tmp_dir `combine` filename
506
507 -- XXX bits copied from System.FilePath, since that's not available here
508 combine a b
509 | null b = a
510 | null a = b
511 | last a == pathSeparator = a ++ b
512 | otherwise = a ++ [pathSeparator] ++ b
513
514 data OpenNewFileResult
515 = NewFileCreated CInt
516 | FileExists
517 | OpenNewError Errno
518
519 openNewFile :: FilePath -> Bool -> CMode -> IO OpenNewFileResult
520 openNewFile filepath binary mode = do
521 let oflags1 = rw_flags .|. o_EXCL
522
523 binary_flags
524 | binary = o_BINARY
525 | otherwise = 0
526
527 oflags = oflags1 .|. binary_flags
528 fd <- withFilePath filepath $ \ f ->
529 c_open f oflags mode
530 if fd < 0
531 then do
532 errno <- getErrno
533 case errno of
534 _ | errno == eEXIST -> return FileExists
535 #ifdef mingw32_HOST_OS
536 -- If c_open throws EACCES on windows, it could mean that filepath is a
537 -- directory. In this case, we want to return FileExists so that the
538 -- enclosing openTempFile can try again instead of failing outright.
539 -- See bug #4968.
540 _ | errno == eACCES -> do
541 withCString filepath $ \path -> do
542 -- There is a race here: the directory might have been moved or
543 -- deleted between the c_open call and the next line, but there
544 -- doesn't seem to be any direct way to detect that the c_open call
545 -- failed because of an existing directory.
546 exists <- c_fileExists path
547 return $ if exists
548 then FileExists
549 else OpenNewError errno
550 #endif
551 _ -> return (OpenNewError errno)
552 else return (NewFileCreated fd)
553
554 #ifdef mingw32_HOST_OS
555 foreign import ccall "file_exists" c_fileExists :: CString -> IO Bool
556 #endif
557
558 -- XXX Should use filepath library
559 pathSeparator :: Char
560 #ifdef mingw32_HOST_OS
561 pathSeparator = '\\'
562 #else
563 pathSeparator = '/'
564 #endif
565
566 -- XXX Copied from GHC.Handle
567 std_flags, output_flags, rw_flags :: CInt
568 std_flags = o_NONBLOCK .|. o_NOCTTY
569 output_flags = std_flags .|. o_CREAT
570 rw_flags = output_flags .|. o_RDWR
571
572 -- $locking
573 -- Implementations should enforce as far as possible, at least locally to the
574 -- Haskell process, multiple-reader single-writer locking on files.
575 -- 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
576 -- open or semi-closed handle is managing a file for output, no new
577 -- handle can be allocated for that file. If any open or semi-closed
578 -- handle is managing a file for input, new handles can only be allocated
579 -- if they do not manage output. Whether two files are the same is
580 -- implementation-dependent, but they should normally be the same if they
581 -- have the same absolute path name and neither has been renamed, for
582 -- example.
583 --
584 -- /Warning/: the 'readFile' operation holds a semi-closed handle on
585 -- the file until the entire contents of the file have been consumed.
586 -- It follows that an attempt to write to a file (using 'writeFile', for
587 -- example) that was earlier opened by 'readFile' will usually result in
588 -- failure with 'System.IO.Error.isAlreadyInUseError'.
589