base: make System.IO.openTempFile generate less predictable names
[ghc.git] / libraries / base / 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 = findTempName
468 where
469 -- We split off the last extension, so we can use .foo.ext files
470 -- for temporary files (hidden on Unix OSes). Unfortunately we're
471 -- below filepath in the hierarchy here.
472 (prefix,suffix) =
473 case break (== '.') $ reverse template of
474 -- First case: template contains no '.'s. Just re-reverse it.
475 (rev_suffix, "") -> (reverse rev_suffix, "")
476 -- Second case: template contains at least one '.'. Strip the
477 -- dot from the prefix and prepend it to the suffix (if we don't
478 -- do this, the unique number will get added after the '.' and
479 -- thus be part of the extension, which is wrong.)
480 (rev_suffix, '.':rest) -> (reverse rest, '.':reverse rev_suffix)
481 -- Otherwise, something is wrong, because (break (== '.')) should
482 -- always return a pair with either the empty string or a string
483 -- beginning with '.' as the second component.
484 _ -> error "bug in System.IO.openTempFile"
485
486 findTempName = do
487 rs <- rand_string
488 let filename = prefix ++ rs ++ suffix
489 filepath = tmp_dir `combine` filename
490 r <- openNewFile filepath binary mode
491 case r of
492 FileExists -> findTempName
493 OpenNewError errno -> ioError (errnoToIOError loc errno Nothing (Just tmp_dir))
494 NewFileCreated fd -> do
495 (fD,fd_type) <- FD.mkFD fd ReadWriteMode Nothing{-no stat-}
496 False{-is_socket-}
497 True{-is_nonblock-}
498
499 enc <- getLocaleEncoding
500 h <- mkHandleFromFD fD fd_type filepath ReadWriteMode False{-set non-block-} (Just enc)
501
502 return (filepath, h)
503
504 where
505 -- XXX bits copied from System.FilePath, since that's not available here
506 combine a b
507 | null b = a
508 | null a = b
509 | last a == pathSeparator = a ++ b
510 | otherwise = a ++ [pathSeparator] ++ b
511
512 -- int rand(void) from <stdlib.h>, limited by RAND_MAX (small value, 32768)
513 foreign import ccall "rand" c_rand :: IO CInt
514
515 -- build large digit-alike number
516 rand_string :: IO String
517 rand_string = do
518 r1 <- c_rand
519 r2 <- c_rand
520 return $ show r1 ++ show r2
521
522 data OpenNewFileResult
523 = NewFileCreated CInt
524 | FileExists
525 | OpenNewError Errno
526
527 openNewFile :: FilePath -> Bool -> CMode -> IO OpenNewFileResult
528 openNewFile filepath binary mode = do
529 let oflags1 = rw_flags .|. o_EXCL
530
531 binary_flags
532 | binary = o_BINARY
533 | otherwise = 0
534
535 oflags = oflags1 .|. binary_flags
536 fd <- withFilePath filepath $ \ f ->
537 c_open f oflags mode
538 if fd < 0
539 then do
540 errno <- getErrno
541 case errno of
542 _ | errno == eEXIST -> return FileExists
543 #ifdef mingw32_HOST_OS
544 -- If c_open throws EACCES on windows, it could mean that filepath is a
545 -- directory. In this case, we want to return FileExists so that the
546 -- enclosing openTempFile can try again instead of failing outright.
547 -- See bug #4968.
548 _ | errno == eACCES -> do
549 withCString filepath $ \path -> do
550 -- There is a race here: the directory might have been moved or
551 -- deleted between the c_open call and the next line, but there
552 -- doesn't seem to be any direct way to detect that the c_open call
553 -- failed because of an existing directory.
554 exists <- c_fileExists path
555 return $ if exists
556 then FileExists
557 else OpenNewError errno
558 #endif
559 _ -> return (OpenNewError errno)
560 else return (NewFileCreated fd)
561
562 #ifdef mingw32_HOST_OS
563 foreign import ccall "file_exists" c_fileExists :: CString -> IO Bool
564 #endif
565
566 -- XXX Should use filepath library
567 pathSeparator :: Char
568 #ifdef mingw32_HOST_OS
569 pathSeparator = '\\'
570 #else
571 pathSeparator = '/'
572 #endif
573
574 -- XXX Copied from GHC.Handle
575 std_flags, output_flags, rw_flags :: CInt
576 std_flags = o_NONBLOCK .|. o_NOCTTY
577 output_flags = std_flags .|. o_CREAT
578 rw_flags = output_flags .|. o_RDWR
579
580 -- $locking
581 -- Implementations should enforce as far as possible, at least locally to the
582 -- Haskell process, multiple-reader single-writer locking on files.
583 -- 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
584 -- open or semi-closed handle is managing a file for output, no new
585 -- handle can be allocated for that file. If any open or semi-closed
586 -- handle is managing a file for input, new handles can only be allocated
587 -- if they do not manage output. Whether two files are the same is
588 -- implementation-dependent, but they should normally be the same if they
589 -- have the same absolute path name and neither has been renamed, for
590 -- example.
591 --
592 -- /Warning/: the 'readFile' operation holds a semi-closed handle on
593 -- the file until the entire contents of the file have been consumed.
594 -- It follows that an attempt to write to a file (using 'writeFile', for
595 -- example) that was earlier opened by 'readFile' will usually result in
596 -- failure with 'System.IO.Error.isAlreadyInUseError'.
597