1796200bc48eeb3001cb627d2c14b6358e42b9f4
[ghc.git] / libraries / base / System / IO.hs
1 {-# LANGUAGE Trustworthy #-}
2 {-# LANGUAGE CPP, NoImplicitPrelude, CApiFFI #-}
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.Maybe
226 import Foreign.C.Error
227 #ifdef mingw32_HOST_OS
228 import Foreign.C.String
229 #endif
230 import Foreign.C.Types
231 import System.Posix.Internals
232 import System.Posix.Types
233
234 import GHC.Base
235 import GHC.List
236 import GHC.IORef
237 import GHC.Num
238 import GHC.IO hiding ( bracket, onException )
239 import GHC.IO.IOMode
240 import GHC.IO.Handle.FD
241 import qualified GHC.IO.FD as FD
242 import GHC.IO.Handle
243 import GHC.IO.Handle.Text ( hGetBufSome, hPutStrLn )
244 import GHC.IO.Exception ( userError )
245 import GHC.IO.Encoding
246 import Text.Read
247 import GHC.Show
248 import GHC.MVar
249
250 -- -----------------------------------------------------------------------------
251 -- Standard IO
252
253 -- | Write a character to the standard output device
254 -- (same as 'hPutChar' 'stdout').
255
256 putChar :: Char -> IO ()
257 putChar c = hPutChar stdout c
258
259 -- | Write a string to the standard output device
260 -- (same as 'hPutStr' 'stdout').
261
262 putStr :: String -> IO ()
263 putStr s = hPutStr stdout s
264
265 -- | The same as 'putStr', but adds a newline character.
266
267 putStrLn :: String -> IO ()
268 putStrLn s = hPutStrLn stdout s
269
270 -- | The 'print' function outputs a value of any printable type to the
271 -- standard output device.
272 -- Printable types are those that are instances of class 'Show'; 'print'
273 -- converts values to strings for output using the 'show' operation and
274 -- adds a newline.
275 --
276 -- For example, a program to print the first 20 integers and their
277 -- powers of 2 could be written as:
278 --
279 -- > main = print ([(n, 2^n) | n <- [0..19]])
280
281 print :: Show a => a -> IO ()
282 print x = putStrLn (show x)
283
284 -- | Read a character from the standard input device
285 -- (same as 'hGetChar' 'stdin').
286
287 getChar :: IO Char
288 getChar = hGetChar stdin
289
290 -- | Read a line from the standard input device
291 -- (same as 'hGetLine' 'stdin').
292
293 getLine :: IO String
294 getLine = hGetLine stdin
295
296 -- | The 'getContents' operation returns all user input as a single string,
297 -- which is read lazily as it is needed
298 -- (same as 'hGetContents' 'stdin').
299
300 getContents :: IO String
301 getContents = hGetContents stdin
302
303 -- | The 'interact' function takes a function of type @String->String@
304 -- as its argument. The entire input from the standard input device is
305 -- passed to this function as its argument, and the resulting string is
306 -- output on the standard output device.
307
308 interact :: (String -> String) -> IO ()
309 interact f = do s <- getContents
310 putStr (f s)
311
312 -- | The 'readFile' function reads a file and
313 -- returns the contents of the file as a string.
314 -- The file is read lazily, on demand, as with 'getContents'.
315
316 readFile :: FilePath -> IO String
317 readFile name = openFile name ReadMode >>= hGetContents
318
319 -- | The computation 'writeFile' @file str@ function writes the string @str@,
320 -- to the file @file@.
321 writeFile :: FilePath -> String -> IO ()
322 writeFile f txt = withFile f WriteMode (\ hdl -> hPutStr hdl txt)
323
324 -- | The computation 'appendFile' @file str@ function appends the string @str@,
325 -- to the file @file@.
326 --
327 -- Note that 'writeFile' and 'appendFile' write a literal string
328 -- to a file. To write a value of any printable type, as with 'print',
329 -- use the 'show' function to convert the value to a string first.
330 --
331 -- > main = appendFile "squares" (show [(x,x*x) | x <- [0,0.1..2]])
332
333 appendFile :: FilePath -> String -> IO ()
334 appendFile f txt = withFile f AppendMode (\ hdl -> hPutStr hdl txt)
335
336 -- | The 'readLn' function combines 'getLine' and 'readIO'.
337
338 readLn :: Read a => IO a
339 readLn = do l <- getLine
340 r <- readIO l
341 return r
342
343 -- | The 'readIO' function is similar to 'read' except that it signals
344 -- parse failure to the 'IO' monad instead of terminating the program.
345
346 readIO :: Read a => String -> IO a
347 readIO s = case (do { (x,t) <- reads s ;
348 ("","") <- lex t ;
349 return x }) of
350 [x] -> return x
351 [] -> ioError (userError "Prelude.readIO: no parse")
352 _ -> ioError (userError "Prelude.readIO: ambiguous parse")
353
354 -- | The Unicode encoding of the current locale
355 --
356 -- This is the initial locale encoding: if it has been subsequently changed by
357 -- 'GHC.IO.Encoding.setLocaleEncoding' this value will not reflect that change.
358 localeEncoding :: TextEncoding
359 localeEncoding = initLocaleEncoding
360
361 -- | Computation 'hReady' @hdl@ indicates whether at least one item is
362 -- available for input from handle @hdl@.
363 --
364 -- This operation may fail with:
365 --
366 -- * 'System.IO.Error.isEOFError' if the end of file has been reached.
367
368 hReady :: Handle -> IO Bool
369 hReady h = hWaitForInput h 0
370
371 -- | Computation 'hPrint' @hdl t@ writes the string representation of @t@
372 -- given by the 'shows' function to the file or channel managed by @hdl@
373 -- and appends a newline.
374 --
375 -- This operation may fail with:
376 --
377 -- * 'System.IO.Error.isFullError' if the device is full; or
378 --
379 -- * 'System.IO.Error.isPermissionError' if another system resource limit would be exceeded.
380
381 hPrint :: Show a => Handle -> a -> IO ()
382 hPrint hdl = hPutStrLn hdl . show
383
384 -- | @'withFile' name mode act@ opens a file using 'openFile' and passes
385 -- the resulting handle to the computation @act@. The handle will be
386 -- closed on exit from 'withFile', whether by normal termination or by
387 -- raising an exception. If closing the handle raises an exception, then
388 -- this exception will be raised by 'withFile' rather than any exception
389 -- raised by 'act'.
390 withFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
391 withFile name mode = bracket (openFile name mode) hClose
392
393 -- | @'withBinaryFile' name mode act@ opens a file using 'openBinaryFile'
394 -- and passes the resulting handle to the computation @act@. The handle
395 -- will be closed on exit from 'withBinaryFile', whether by normal
396 -- termination or by raising an exception.
397 withBinaryFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
398 withBinaryFile name mode = bracket (openBinaryFile name mode) hClose
399
400 -- ---------------------------------------------------------------------------
401 -- fixIO
402
403 fixIO :: (a -> IO a) -> IO a
404 fixIO k = do
405 m <- newEmptyMVar
406 ans <- unsafeInterleaveIO (takeMVar m)
407 result <- k ans
408 putMVar m result
409 return result
410
411 -- NOTE: we do our own explicit black holing here, because GHC's lazy
412 -- blackholing isn't enough. In an infinite loop, GHC may run the IO
413 -- computation a few times before it notices the loop, which is wrong.
414 --
415 -- NOTE2: the explicit black-holing with an IORef ran into trouble
416 -- with multiple threads (see #5421), so now we use an MVar. I'm
417 -- actually wondering whether we should use readMVar rather than
418 -- takeMVar, just in case it ends up being executed multiple times,
419 -- but even then it would have to be masked to protect against async
420 -- exceptions. Ugh. What we really need here is an IVar, or an
421 -- atomic readMVar, or even STM. All these seem like overkill.
422 --
423 -- See also System.IO.Unsafe.unsafeFixIO.
424 --
425
426 -- | The function creates a temporary file in ReadWrite mode.
427 -- The created file isn\'t deleted automatically, so you need to delete it manually.
428 --
429 -- The file is created with permissions such that only the current
430 -- user can read\/write it.
431 --
432 -- With some exceptions (see below), the file will be created securely
433 -- in the sense that an attacker should not be able to cause
434 -- openTempFile to overwrite another file on the filesystem using your
435 -- credentials, by putting symbolic links (on Unix) in the place where
436 -- the temporary file is to be created. On Unix the @O_CREAT@ and
437 -- @O_EXCL@ flags are used to prevent this attack, but note that
438 -- @O_EXCL@ is sometimes not supported on NFS filesystems, so if you
439 -- rely on this behaviour it is best to use local filesystems only.
440 --
441 openTempFile :: FilePath -- ^ Directory in which to create the file
442 -> String -- ^ File name template. If the template is \"foo.ext\" then
443 -- the created file will be \"fooXXX.ext\" where XXX is some
444 -- random number. Note that this should not contain any path
445 -- separator characters.
446 -> IO (FilePath, Handle)
447 openTempFile tmp_dir template
448 = openTempFile' "openTempFile" tmp_dir template False 0o600
449
450 -- | Like 'openTempFile', but opens the file in binary mode. See 'openBinaryFile' for more comments.
451 openBinaryTempFile :: FilePath -> String -> IO (FilePath, Handle)
452 openBinaryTempFile tmp_dir template
453 = openTempFile' "openBinaryTempFile" tmp_dir template True 0o600
454
455 -- | Like 'openTempFile', but uses the default file permissions
456 openTempFileWithDefaultPermissions :: FilePath -> String
457 -> IO (FilePath, Handle)
458 openTempFileWithDefaultPermissions tmp_dir template
459 = openTempFile' "openTempFileWithDefaultPermissions" tmp_dir template False 0o666
460
461 -- | Like 'openBinaryTempFile', but uses the default file permissions
462 openBinaryTempFileWithDefaultPermissions :: FilePath -> String
463 -> IO (FilePath, Handle)
464 openBinaryTempFileWithDefaultPermissions tmp_dir template
465 = openTempFile' "openBinaryTempFileWithDefaultPermissions" tmp_dir template True 0o666
466
467 openTempFile' :: String -> FilePath -> String -> Bool -> CMode
468 -> IO (FilePath, Handle)
469 openTempFile' loc tmp_dir template binary mode
470 | pathSeparator `elem` template
471 = fail $ "openTempFile': Template string must not contain path separator characters: "++template
472 | otherwise = findTempName
473 where
474 -- We split off the last extension, so we can use .foo.ext files
475 -- for temporary files (hidden on Unix OSes). Unfortunately we're
476 -- below filepath in the hierarchy here.
477 (prefix,suffix) =
478 case break (== '.') $ reverse template of
479 -- First case: template contains no '.'s. Just re-reverse it.
480 (rev_suffix, "") -> (reverse rev_suffix, "")
481 -- Second case: template contains at least one '.'. Strip the
482 -- dot from the prefix and prepend it to the suffix (if we don't
483 -- do this, the unique number will get added after the '.' and
484 -- thus be part of the extension, which is wrong.)
485 (rev_suffix, '.':rest) -> (reverse rest, '.':reverse rev_suffix)
486 -- Otherwise, something is wrong, because (break (== '.')) should
487 -- always return a pair with either the empty string or a string
488 -- beginning with '.' as the second component.
489 _ -> errorWithoutStackTrace "bug in System.IO.openTempFile"
490
491 findTempName = do
492 rs <- rand_string
493 let filename = prefix ++ rs ++ suffix
494 filepath = tmp_dir `combine` filename
495 r <- openNewFile filepath binary mode
496 case r of
497 FileExists -> findTempName
498 OpenNewError errno -> ioError (errnoToIOError loc errno Nothing (Just tmp_dir))
499 NewFileCreated fd -> do
500 (fD,fd_type) <- FD.mkFD fd ReadWriteMode Nothing{-no stat-}
501 False{-is_socket-}
502 True{-is_nonblock-}
503
504 enc <- getLocaleEncoding
505 h <- mkHandleFromFD fD fd_type filepath ReadWriteMode False{-set non-block-} (Just enc)
506
507 return (filepath, h)
508
509 where
510 -- XXX bits copied from System.FilePath, since that's not available here
511 combine a b
512 | null b = a
513 | null a = b
514 | last a == pathSeparator = a ++ b
515 | otherwise = a ++ [pathSeparator] ++ b
516
517 tempCounter :: IORef Int
518 tempCounter = unsafePerformIO $ newIORef 0
519 {-# NOINLINE tempCounter #-}
520
521 -- build large digit-alike number
522 rand_string :: IO String
523 rand_string = do
524 r1 <- c_getpid
525 r2 <- atomicModifyIORef tempCounter (\n -> (n+1, n))
526 return $ show r1 ++ "-" ++ show r2
527
528 data OpenNewFileResult
529 = NewFileCreated CInt
530 | FileExists
531 | OpenNewError Errno
532
533 openNewFile :: FilePath -> Bool -> CMode -> IO OpenNewFileResult
534 openNewFile filepath binary mode = do
535 let oflags1 = rw_flags .|. o_EXCL
536
537 binary_flags
538 | binary = o_BINARY
539 | otherwise = 0
540
541 oflags = oflags1 .|. binary_flags
542 fd <- withFilePath filepath $ \ f ->
543 c_open f oflags mode
544 if fd < 0
545 then do
546 errno <- getErrno
547 case errno of
548 _ | errno == eEXIST -> return FileExists
549 #ifdef mingw32_HOST_OS
550 -- If c_open throws EACCES on windows, it could mean that filepath is a
551 -- directory. In this case, we want to return FileExists so that the
552 -- enclosing openTempFile can try again instead of failing outright.
553 -- See bug #4968.
554 _ | errno == eACCES -> do
555 withCString filepath $ \path -> do
556 -- There is a race here: the directory might have been moved or
557 -- deleted between the c_open call and the next line, but there
558 -- doesn't seem to be any direct way to detect that the c_open call
559 -- failed because of an existing directory.
560 exists <- c_fileExists path
561 return $ if exists
562 then FileExists
563 else OpenNewError errno
564 #endif
565 _ -> return (OpenNewError errno)
566 else return (NewFileCreated fd)
567
568 #ifdef mingw32_HOST_OS
569 foreign import ccall "file_exists" c_fileExists :: CString -> IO Bool
570 #endif
571
572 -- XXX Should use filepath library
573 pathSeparator :: Char
574 #ifdef mingw32_HOST_OS
575 pathSeparator = '\\'
576 #else
577 pathSeparator = '/'
578 #endif
579
580 -- XXX Copied from GHC.Handle
581 std_flags, output_flags, rw_flags :: CInt
582 std_flags = o_NONBLOCK .|. o_NOCTTY
583 output_flags = std_flags .|. o_CREAT
584 rw_flags = output_flags .|. o_RDWR
585
586 -- $locking
587 -- Implementations should enforce as far as possible, at least locally to the
588 -- Haskell process, multiple-reader single-writer locking on files.
589 -- 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
590 -- open or semi-closed handle is managing a file for output, no new
591 -- handle can be allocated for that file. If any open or semi-closed
592 -- handle is managing a file for input, new handles can only be allocated
593 -- if they do not manage output. Whether two files are the same is
594 -- implementation-dependent, but they should normally be the same if they
595 -- have the same absolute path name and neither has been renamed, for
596 -- example.
597 --
598 -- /Warning/: the 'readFile' operation holds a semi-closed handle on
599 -- the file until the entire contents of the file have been consumed.
600 -- It follows that an attempt to write to a file (using 'writeFile', for
601 -- example) that was earlier opened by 'readFile' will usually result in
602 -- failure with 'System.IO.Error.isAlreadyInUseError'.
603