1 {-# OPTIONS_GHC -XNoImplicitPrelude #-}
2 -----------------------------------------------------------------------------
5 -- Copyright : (c) The University of Glasgow 2001
6 -- License : BSD-style (see the file libraries/base/LICENSE)
8 -- Maintainer : libraries@haskell.org
10 -- Portability : portable
12 -- The standard IO library.
14 -----------------------------------------------------------------------------
19 IO, -- instance MonadFix
20 fixIO, -- :: (a -> IO a) -> IO a
22 -- * Files and handles
24 FilePath, -- :: String
26 Handle, -- abstract, instance of: Eq, Show.
28 -- | GHC note: a 'Handle' will be automatically closed when the garbage
29 -- collector detects that it has become unreferenced by the program.
30 -- However, relying on this behaviour is not generally recommended:
31 -- the garbage collector is unpredictable. If possible, use
32 -- an explicit 'hClose' to close 'Handle's when they are no longer
33 -- required. GHC does not currently attempt to free up file
34 -- descriptors when they have run out, it is your responsibility to
35 -- ensure that this doesn't happen.
37 -- ** Standard handles
39 -- | Three handles are allocated during program initialisation,
40 -- and are initially open.
42 stdin, stdout, stderr, -- :: Handle
44 -- * Opening and closing files
49 openFile, -- :: FilePath -> IOMode -> IO Handle
50 IOMode(ReadMode,WriteMode,AppendMode,ReadWriteMode),
54 hClose, -- :: Handle -> IO ()
58 -- | These functions are also exported by the "Prelude".
60 readFile, -- :: FilePath -> IO String
61 writeFile, -- :: FilePath -> String -> IO ()
62 appendFile, -- :: FilePath -> String -> IO ()
68 -- * Operations on handles
70 -- ** Determining and changing the size of a file
72 hFileSize, -- :: Handle -> IO Integer
73 #ifdef __GLASGOW_HASKELL__
74 hSetFileSize, -- :: Handle -> Integer -> IO ()
77 -- ** Detecting the end of input
79 hIsEOF, -- :: Handle -> IO Bool
82 -- ** Buffering operations
84 BufferMode(NoBuffering,LineBuffering,BlockBuffering),
85 hSetBuffering, -- :: Handle -> BufferMode -> IO ()
86 hGetBuffering, -- :: Handle -> IO BufferMode
87 hFlush, -- :: Handle -> IO ()
89 -- ** Repositioning handles
91 hGetPosn, -- :: Handle -> IO HandlePosn
92 hSetPosn, -- :: HandlePosn -> IO ()
93 HandlePosn, -- abstract, instance of: Eq, Show.
95 hSeek, -- :: Handle -> SeekMode -> Integer -> IO ()
96 SeekMode(AbsoluteSeek,RelativeSeek,SeekFromEnd),
98 hTell, -- :: Handle -> IO Integer
101 -- ** Handle properties
103 hIsOpen, hIsClosed, -- :: Handle -> IO Bool
104 hIsReadable, hIsWritable, -- :: Handle -> IO Bool
105 hIsSeekable, -- :: Handle -> IO Bool
107 -- ** Terminal operations (not portable: GHC\/Hugs only)
109 #if !defined(__NHC__)
110 hIsTerminalDevice, -- :: Handle -> IO Bool
112 hSetEcho, -- :: Handle -> Bool -> IO ()
113 hGetEcho, -- :: Handle -> IO Bool
116 -- ** Showing handle state (not portable: GHC only)
118 #ifdef __GLASGOW_HASKELL__
119 hShow, -- :: Handle -> IO String
122 -- * Text input and output
126 hWaitForInput, -- :: Handle -> Int -> IO Bool
127 hReady, -- :: Handle -> IO Bool
128 hGetChar, -- :: Handle -> IO Char
129 hGetLine, -- :: Handle -> IO [Char]
130 hLookAhead, -- :: Handle -> IO Char
131 hGetContents, -- :: Handle -> IO [Char]
135 hPutChar, -- :: Handle -> Char -> IO ()
136 hPutStr, -- :: Handle -> [Char] -> IO ()
137 hPutStrLn, -- :: Handle -> [Char] -> IO ()
138 hPrint, -- :: Show a => Handle -> a -> IO ()
140 -- ** Special cases for standard input and output
142 -- | These functions are also exported by the "Prelude".
144 interact, -- :: (String -> String) -> IO ()
145 putChar, -- :: Char -> IO ()
146 putStr, -- :: String -> IO ()
147 putStrLn, -- :: String -> IO ()
148 print, -- :: Show a => a -> IO ()
149 getChar, -- :: IO Char
150 getLine, -- :: IO String
151 getContents, -- :: IO String
152 readIO, -- :: Read a => String -> IO a
153 readLn, -- :: Read a => IO a
155 -- * Binary input and output
158 openBinaryFile, -- :: FilePath -> IOMode -> IO Handle
159 hSetBinaryMode, -- :: Handle -> Bool -> IO ()
160 hPutBuf, -- :: Handle -> Ptr a -> Int -> IO ()
161 hGetBuf, -- :: Handle -> Ptr a -> Int -> IO Int
162 #if !defined(__NHC__) && !defined(__HUGS__)
163 hGetBufSome, -- :: Handle -> Ptr a -> Int -> IO Int
164 hPutBufNonBlocking, -- :: Handle -> Ptr a -> Int -> IO Int
165 hGetBufNonBlocking, -- :: Handle -> Ptr a -> Int -> IO Int
172 openTempFileWithDefaultPermissions,
173 openBinaryTempFileWithDefaultPermissions,
175 #if !defined(__NHC__) && !defined(__HUGS__)
176 -- * Unicode encoding\/decoding
178 -- | A text-mode 'Handle' has an associated 'TextEncoding', which
179 -- is used to decode bytes into Unicode characters when reading,
180 -- and encode Unicode characters into bytes when writing.
182 -- The default 'TextEncoding' is the same as the default encoding
183 -- on your system, which is also available as 'localeEncoding'.
184 -- (GHC note: on Windows, we currently do not support double-byte
185 -- encodings; if the console\'s code page is unsupported, then
186 -- 'localeEncoding' will be 'latin1'.)
188 -- Encoding and decoding errors are always detected and reported,
189 -- except during lazy I/O ('hGetContents', 'getContents', and
190 -- 'readFile'), where a decoding error merely results in
191 -- termination of the character stream, as with other I/O errors.
196 -- ** Unicode encodings
200 utf16, utf16le, utf16be,
201 utf32, utf32le, utf32be,
206 #if !defined(__NHC__) && !defined(__HUGS__)
207 -- * Newline conversion
209 -- | In Haskell, a newline is always represented by the character
210 -- '\n'. However, in files and external character streams, a
211 -- newline may be represented by another character sequence, such
214 -- A text-mode 'Handle' has an associated 'NewlineMode' that
215 -- specifies how to transate newline characters. The
216 -- 'NewlineMode' specifies the input and output translation
217 -- separately, so that for instance you can translate '\r\n'
218 -- to '\n' on input, but leave newlines as '\n' on output.
220 -- The default 'NewlineMode' for a 'Handle' is
221 -- 'nativeNewlineMode', which does no translation on Unix systems,
222 -- but translates '\r\n' to '\n' and back on Windows.
224 -- Binary-mode 'Handle's do no newline translation at all.
227 Newline(..), nativeNewline,
229 noNewlineTranslation, universalNewlineMode, nativeNewlineMode,
233 import Control.Exception.Base
239 import Foreign.C.Error
240 import Foreign.C.Types
241 import System.Posix.Internals
242 import System.Posix.Types
245 #ifdef __GLASGOW_HASKELL__
248 import GHC.IO hiding ( onException )
250 import GHC.IO.Handle.FD
251 import qualified GHC.IO.FD as FD
253 import GHC.IO.Handle.Text ( hGetBufSome )
255 import GHC.IO.Exception ( userError )
256 import GHC.IO.Encoding
266 import System.IO.Unsafe ( unsafeInterleaveIO )
273 , IOMode (ReadMode,WriteMode,AppendMode,ReadWriteMode)
274 , BufferMode (NoBuffering,LineBuffering,BlockBuffering)
275 , SeekMode (AbsoluteSeek,RelativeSeek,SeekFromEnd)
276 , stdin, stdout, stderr
277 , openFile -- :: FilePath -> IOMode -> IO Handle
278 , hClose -- :: Handle -> IO ()
279 , hFileSize -- :: Handle -> IO Integer
280 , hIsEOF -- :: Handle -> IO Bool
281 , isEOF -- :: IO Bool
282 , hSetBuffering -- :: Handle -> BufferMode -> IO ()
283 , hGetBuffering -- :: Handle -> IO BufferMode
284 , hFlush -- :: Handle -> IO ()
285 , hGetPosn -- :: Handle -> IO HandlePosn
286 , hSetPosn -- :: HandlePosn -> IO ()
287 , hSeek -- :: Handle -> SeekMode -> Integer -> IO ()
288 , hWaitForInput -- :: Handle -> Int -> IO Bool
289 , hGetChar -- :: Handle -> IO Char
290 , hGetLine -- :: Handle -> IO [Char]
291 , hLookAhead -- :: Handle -> IO Char
292 , hGetContents -- :: Handle -> IO [Char]
293 , hPutChar -- :: Handle -> Char -> IO ()
294 , hPutStr -- :: Handle -> [Char] -> IO ()
295 , hPutStrLn -- :: Handle -> [Char] -> IO ()
296 , hPrint -- :: Handle -> [Char] -> IO ()
297 , hReady -- :: Handle -> [Char] -> IO ()
298 , hIsOpen, hIsClosed -- :: Handle -> IO Bool
299 , hIsReadable, hIsWritable -- :: Handle -> IO Bool
300 , hIsSeekable -- :: Handle -> IO Bool
304 , FilePath -- :: String
306 import NHC.IOExtras (fixIO, hPutBuf, hGetBuf)
310 -- -----------------------------------------------------------------------------
313 #ifdef __GLASGOW_HASKELL__
314 -- | Write a character to the standard output device
315 -- (same as 'hPutChar' 'stdout').
317 putChar :: Char -> IO ()
318 putChar c = hPutChar stdout c
320 -- | Write a string to the standard output device
321 -- (same as 'hPutStr' 'stdout').
323 putStr :: String -> IO ()
324 putStr s = hPutStr stdout s
326 -- | The same as 'putStr', but adds a newline character.
328 putStrLn :: String -> IO ()
329 putStrLn s = do putStr s
332 -- | The 'print' function outputs a value of any printable type to the
333 -- standard output device.
334 -- Printable types are those that are instances of class 'Show'; 'print'
335 -- converts values to strings for output using the 'show' operation and
338 -- For example, a program to print the first 20 integers and their
339 -- powers of 2 could be written as:
341 -- > main = print ([(n, 2^n) | n <- [0..19]])
343 print :: Show a => a -> IO ()
344 print x = putStrLn (show x)
346 -- | Read a character from the standard input device
347 -- (same as 'hGetChar' 'stdin').
350 getChar = hGetChar stdin
352 -- | Read a line from the standard input device
353 -- (same as 'hGetLine' 'stdin').
356 getLine = hGetLine stdin
358 -- | The 'getContents' operation returns all user input as a single string,
359 -- which is read lazily as it is needed
360 -- (same as 'hGetContents' 'stdin').
362 getContents :: IO String
363 getContents = hGetContents stdin
365 -- | The 'interact' function takes a function of type @String->String@
366 -- as its argument. The entire input from the standard input device is
367 -- passed to this function as its argument, and the resulting string is
368 -- output on the standard output device.
370 interact :: (String -> String) -> IO ()
371 interact f = do s <- getContents
374 -- | The 'readFile' function reads a file and
375 -- returns the contents of the file as a string.
376 -- The file is read lazily, on demand, as with 'getContents'.
378 readFile :: FilePath -> IO String
379 readFile name = openFile name ReadMode >>= hGetContents
381 -- | The computation 'writeFile' @file str@ function writes the string @str@,
382 -- to the file @file@.
383 writeFile :: FilePath -> String -> IO ()
384 writeFile f txt = withFile f WriteMode (\ hdl -> hPutStr hdl txt)
386 -- | The computation 'appendFile' @file str@ function appends the string @str@,
387 -- to the file @file@.
389 -- Note that 'writeFile' and 'appendFile' write a literal string
390 -- to a file. To write a value of any printable type, as with 'print',
391 -- use the 'show' function to convert the value to a string first.
393 -- > main = appendFile "squares" (show [(x,x*x) | x <- [0,0.1..2]])
395 appendFile :: FilePath -> String -> IO ()
396 appendFile f txt = withFile f AppendMode (\ hdl -> hPutStr hdl txt)
398 -- | The 'readLn' function combines 'getLine' and 'readIO'.
400 readLn :: Read a => IO a
401 readLn = do l <- getLine
405 -- | The 'readIO' function is similar to 'read' except that it signals
406 -- parse failure to the 'IO' monad instead of terminating the program.
408 readIO :: Read a => String -> IO a
409 readIO s = case (do { (x,t) <- reads s ;
413 [] -> ioError (userError "Prelude.readIO: no parse")
414 _ -> ioError (userError "Prelude.readIO: ambiguous parse")
415 #endif /* __GLASGOW_HASKELL__ */
418 -- | Computation 'hReady' @hdl@ indicates whether at least one item is
419 -- available for input from handle @hdl@.
421 -- This operation may fail with:
423 -- * 'System.IO.Error.isEOFError' if the end of file has been reached.
425 hReady :: Handle -> IO Bool
426 hReady h = hWaitForInput h 0
428 -- | The same as 'hPutStr', but adds a newline character.
430 hPutStrLn :: Handle -> String -> IO ()
431 hPutStrLn hndl str = do
435 -- | Computation 'hPrint' @hdl t@ writes the string representation of @t@
436 -- given by the 'shows' function to the file or channel managed by @hdl@
437 -- and appends a newline.
439 -- This operation may fail with:
441 -- * 'System.IO.Error.isFullError' if the device is full; or
443 -- * 'System.IO.Error.isPermissionError' if another system resource limit would be exceeded.
445 hPrint :: Show a => Handle -> a -> IO ()
446 hPrint hdl = hPutStrLn hdl . show
447 #endif /* !__NHC__ */
449 -- | @'withFile' name mode act@ opens a file using 'openFile' and passes
450 -- the resulting handle to the computation @act@. The handle will be
451 -- closed on exit from 'withFile', whether by normal termination or by
452 -- raising an exception. If closing the handle raises an exception, then
453 -- this exception will be raised by 'withFile' rather than any exception
455 withFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
456 withFile name mode = bracket (openFile name mode) hClose
458 -- | @'withBinaryFile' name mode act@ opens a file using 'openBinaryFile'
459 -- and passes the resulting handle to the computation @act@. The handle
460 -- will be closed on exit from 'withBinaryFile', whether by normal
461 -- termination or by raising an exception.
462 withBinaryFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
463 withBinaryFile name mode = bracket (openBinaryFile name mode) hClose
465 -- ---------------------------------------------------------------------------
468 #if defined(__GLASGOW_HASKELL__) || defined(__HUGS__)
469 fixIO :: (a -> IO a) -> IO a
471 ref <- newIORef (throw NonTermination)
472 ans <- unsafeInterleaveIO (readIORef ref)
474 writeIORef ref result
477 -- NOTE: we do our own explicit black holing here, because GHC's lazy
478 -- blackholing isn't enough. In an infinite loop, GHC may run the IO
479 -- computation a few times before it notices the loop, which is wrong.
483 -- Assume a unix platform, where text and binary I/O are identical.
484 openBinaryFile = openFile
485 hSetBinaryMode _ _ = return ()
490 -- | The function creates a temporary file in ReadWrite mode.
491 -- The created file isn\'t deleted automatically, so you need to delete it manually.
493 -- The file is creates with permissions such that only the current
494 -- user can read\/write it.
496 -- With some exceptions (see below), the file will be created securely
497 -- in the sense that an attacker should not be able to cause
498 -- openTempFile to overwrite another file on the filesystem using your
499 -- credentials, by putting symbolic links (on Unix) in the place where
500 -- the temporary file is to be created. On Unix the @O_CREAT@ and
501 -- @O_EXCL@ flags are used to prevent this attack, but note that
502 -- @O_EXCL@ is sometimes not supported on NFS filesystems, so if you
503 -- rely on this behaviour it is best to use local filesystems only.
505 openTempFile :: FilePath -- ^ Directory in which to create the file
506 -> String -- ^ File name template. If the template is \"foo.ext\" then
507 -- the created file will be \"fooXXX.ext\" where XXX is some
509 -> IO (FilePath, Handle)
510 openTempFile tmp_dir template
511 = openTempFile' "openTempFile" tmp_dir template False 0o600
513 -- | Like 'openTempFile', but opens the file in binary mode. See 'openBinaryFile' for more comments.
514 openBinaryTempFile :: FilePath -> String -> IO (FilePath, Handle)
515 openBinaryTempFile tmp_dir template
516 = openTempFile' "openBinaryTempFile" tmp_dir template True 0o600
518 -- | Like 'openTempFile', but uses the default file permissions
519 openTempFileWithDefaultPermissions :: FilePath -> String
520 -> IO (FilePath, Handle)
521 openTempFileWithDefaultPermissions tmp_dir template
522 = openTempFile' "openBinaryTempFile" tmp_dir template False 0o666
524 -- | Like 'openBinaryTempFile', but uses the default file permissions
525 openBinaryTempFileWithDefaultPermissions :: FilePath -> String
526 -> IO (FilePath, Handle)
527 openBinaryTempFileWithDefaultPermissions tmp_dir template
528 = openTempFile' "openBinaryTempFile" tmp_dir template True 0o666
530 openTempFile' :: String -> FilePath -> String -> Bool -> CMode
531 -> IO (FilePath, Handle)
532 openTempFile' loc tmp_dir template binary mode = do
536 -- We split off the last extension, so we can use .foo.ext files
537 -- for temporary files (hidden on Unix OSes). Unfortunately we're
538 -- below filepath in the hierarchy here.
540 case break (== '.') $ reverse template of
541 -- First case: template contains no '.'s. Just re-reverse it.
542 (rev_suffix, "") -> (reverse rev_suffix, "")
543 -- Second case: template contains at least one '.'. Strip the
544 -- dot from the prefix and prepend it to the suffix (if we don't
545 -- do this, the unique number will get added after the '.' and
546 -- thus be part of the extension, which is wrong.)
547 (rev_suffix, '.':rest) -> (reverse rest, '.':reverse rev_suffix)
548 -- Otherwise, something is wrong, because (break (== '.')) should
549 -- always return a pair with either the empty string or a string
550 -- beginning with '.' as the second component.
551 _ -> error "bug in System.IO.openTempFile"
554 oflags1 = rw_flags .|. o_EXCL
560 oflags = oflags1 .|. binary_flags
564 findTempName x = do h <- openFile filepath ReadWriteMode
566 #elif defined(__GLASGOW_HASKELL__)
568 fd <- withFilePath filepath $ \ f ->
574 then findTempName (x+1)
575 else ioError (errnoToIOError loc errno Nothing (Just tmp_dir))
578 (fD,fd_type) <- FD.mkFD (fromIntegral fd) ReadWriteMode Nothing{-no stat-}
582 h <- mkHandleFromFD fD fd_type filepath ReadWriteMode False{-set non-block-}
583 (Just localeEncoding)
587 h <- fdToHandle fd `onException` c_close fd
592 filename = prefix ++ show x ++ suffix
593 filepath = tmp_dir `combine` filename
595 -- XXX bits copied from System.FilePath, since that's not available here
599 | last a == pathSeparator = a ++ b
600 | otherwise = a ++ [pathSeparator] ++ b
603 fdToHandle fd = openFd (fromIntegral fd) False ReadWriteMode binary
606 -- XXX Should use filepath library
607 pathSeparator :: Char
608 #ifdef mingw32_HOST_OS
615 -- XXX Copied from GHC.Handle
616 std_flags, output_flags, rw_flags :: CInt
617 std_flags = o_NONBLOCK .|. o_NOCTTY
618 output_flags = std_flags .|. o_CREAT
619 rw_flags = output_flags .|. o_RDWR
623 foreign import ccall "getpid" c_getpid :: IO Int
627 -- Implementations should enforce as far as possible, at least locally to the
628 -- Haskell process, multiple-reader single-writer locking on files.
629 -- 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
630 -- open or semi-closed handle is managing a file for output, no new
631 -- handle can be allocated for that file. If any open or semi-closed
632 -- handle is managing a file for input, new handles can only be allocated
633 -- if they do not manage output. Whether two files are the same is
634 -- implementation-dependent, but they should normally be the same if they
635 -- have the same absolute path name and neither has been renamed, for
638 -- /Warning/: the 'readFile' operation holds a semi-closed handle on
639 -- the file until the entire contents of the file have been consumed.
640 -- It follows that an attempt to write to a file (using 'writeFile', for
641 -- example) that was earlier opened by 'readFile' will usually result in
642 -- failure with 'System.IO.Error.isAlreadyInUseError'.