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__
247 import GHC.IO hiding ( onException )
249 import GHC.IO.Handle.FD
250 import qualified GHC.IO.FD as FD
252 import GHC.IO.Handle.Text ( hGetBufSome )
254 import GHC.IO.Exception ( userError )
255 import GHC.IO.Encoding
265 import System.IO.Unsafe ( unsafeInterleaveIO )
272 , IOMode (ReadMode,WriteMode,AppendMode,ReadWriteMode)
273 , BufferMode (NoBuffering,LineBuffering,BlockBuffering)
274 , SeekMode (AbsoluteSeek,RelativeSeek,SeekFromEnd)
275 , stdin, stdout, stderr
276 , openFile -- :: FilePath -> IOMode -> IO Handle
277 , hClose -- :: Handle -> IO ()
278 , hFileSize -- :: Handle -> IO Integer
279 , hIsEOF -- :: Handle -> IO Bool
280 , isEOF -- :: IO Bool
281 , hSetBuffering -- :: Handle -> BufferMode -> IO ()
282 , hGetBuffering -- :: Handle -> IO BufferMode
283 , hFlush -- :: Handle -> IO ()
284 , hGetPosn -- :: Handle -> IO HandlePosn
285 , hSetPosn -- :: HandlePosn -> IO ()
286 , hSeek -- :: Handle -> SeekMode -> Integer -> IO ()
287 , hWaitForInput -- :: Handle -> Int -> IO Bool
288 , hGetChar -- :: Handle -> IO Char
289 , hGetLine -- :: Handle -> IO [Char]
290 , hLookAhead -- :: Handle -> IO Char
291 , hGetContents -- :: Handle -> IO [Char]
292 , hPutChar -- :: Handle -> Char -> IO ()
293 , hPutStr -- :: Handle -> [Char] -> IO ()
294 , hPutStrLn -- :: Handle -> [Char] -> IO ()
295 , hPrint -- :: Handle -> [Char] -> IO ()
296 , hReady -- :: Handle -> [Char] -> IO ()
297 , hIsOpen, hIsClosed -- :: Handle -> IO Bool
298 , hIsReadable, hIsWritable -- :: Handle -> IO Bool
299 , hIsSeekable -- :: Handle -> IO Bool
303 , FilePath -- :: String
305 import NHC.IOExtras (fixIO, hPutBuf, hGetBuf)
309 -- -----------------------------------------------------------------------------
312 #ifdef __GLASGOW_HASKELL__
313 -- | Write a character to the standard output device
314 -- (same as 'hPutChar' 'stdout').
316 putChar :: Char -> IO ()
317 putChar c = hPutChar stdout c
319 -- | Write a string to the standard output device
320 -- (same as 'hPutStr' 'stdout').
322 putStr :: String -> IO ()
323 putStr s = hPutStr stdout s
325 -- | The same as 'putStr', but adds a newline character.
327 putStrLn :: String -> IO ()
328 putStrLn s = do putStr s
331 -- | The 'print' function outputs a value of any printable type to the
332 -- standard output device.
333 -- Printable types are those that are instances of class 'Show'; 'print'
334 -- converts values to strings for output using the 'show' operation and
337 -- For example, a program to print the first 20 integers and their
338 -- powers of 2 could be written as:
340 -- > main = print ([(n, 2^n) | n <- [0..19]])
342 print :: Show a => a -> IO ()
343 print x = putStrLn (show x)
345 -- | Read a character from the standard input device
346 -- (same as 'hGetChar' 'stdin').
349 getChar = hGetChar stdin
351 -- | Read a line from the standard input device
352 -- (same as 'hGetLine' 'stdin').
355 getLine = hGetLine stdin
357 -- | The 'getContents' operation returns all user input as a single string,
358 -- which is read lazily as it is needed
359 -- (same as 'hGetContents' 'stdin').
361 getContents :: IO String
362 getContents = hGetContents stdin
364 -- | The 'interact' function takes a function of type @String->String@
365 -- as its argument. The entire input from the standard input device is
366 -- passed to this function as its argument, and the resulting string is
367 -- output on the standard output device.
369 interact :: (String -> String) -> IO ()
370 interact f = do s <- getContents
373 -- | The 'readFile' function reads a file and
374 -- returns the contents of the file as a string.
375 -- The file is read lazily, on demand, as with 'getContents'.
377 readFile :: FilePath -> IO String
378 readFile name = openFile name ReadMode >>= hGetContents
380 -- | The computation 'writeFile' @file str@ function writes the string @str@,
381 -- to the file @file@.
382 writeFile :: FilePath -> String -> IO ()
383 writeFile f txt = withFile f WriteMode (\ hdl -> hPutStr hdl txt)
385 -- | The computation 'appendFile' @file str@ function appends the string @str@,
386 -- to the file @file@.
388 -- Note that 'writeFile' and 'appendFile' write a literal string
389 -- to a file. To write a value of any printable type, as with 'print',
390 -- use the 'show' function to convert the value to a string first.
392 -- > main = appendFile "squares" (show [(x,x*x) | x <- [0,0.1..2]])
394 appendFile :: FilePath -> String -> IO ()
395 appendFile f txt = withFile f AppendMode (\ hdl -> hPutStr hdl txt)
397 -- | The 'readLn' function combines 'getLine' and 'readIO'.
399 readLn :: Read a => IO a
400 readLn = do l <- getLine
404 -- | The 'readIO' function is similar to 'read' except that it signals
405 -- parse failure to the 'IO' monad instead of terminating the program.
407 readIO :: Read a => String -> IO a
408 readIO s = case (do { (x,t) <- reads s ;
412 [] -> ioError (userError "Prelude.readIO: no parse")
413 _ -> ioError (userError "Prelude.readIO: ambiguous parse")
414 #endif /* __GLASGOW_HASKELL__ */
417 -- | Computation 'hReady' @hdl@ indicates whether at least one item is
418 -- available for input from handle @hdl@.
420 -- This operation may fail with:
422 -- * 'System.IO.Error.isEOFError' if the end of file has been reached.
424 hReady :: Handle -> IO Bool
425 hReady h = hWaitForInput h 0
427 -- | The same as 'hPutStr', but adds a newline character.
429 hPutStrLn :: Handle -> String -> IO ()
430 hPutStrLn hndl str = do
434 -- | Computation 'hPrint' @hdl t@ writes the string representation of @t@
435 -- given by the 'shows' function to the file or channel managed by @hdl@
436 -- and appends a newline.
438 -- This operation may fail with:
440 -- * 'System.IO.Error.isFullError' if the device is full; or
442 -- * 'System.IO.Error.isPermissionError' if another system resource limit would be exceeded.
444 hPrint :: Show a => Handle -> a -> IO ()
445 hPrint hdl = hPutStrLn hdl . show
446 #endif /* !__NHC__ */
448 -- | @'withFile' name mode act@ opens a file using 'openFile' and passes
449 -- the resulting handle to the computation @act@. The handle will be
450 -- closed on exit from 'withFile', whether by normal termination or by
451 -- raising an exception. If closing the handle raises an exception, then
452 -- this exception will be raised by 'withFile' rather than any exception
454 withFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
455 withFile name mode = bracket (openFile name mode) hClose
457 -- | @'withBinaryFile' name mode act@ opens a file using 'openBinaryFile'
458 -- and passes the resulting handle to the computation @act@. The handle
459 -- will be closed on exit from 'withBinaryFile', whether by normal
460 -- termination or by raising an exception.
461 withBinaryFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
462 withBinaryFile name mode = bracket (openBinaryFile name mode) hClose
464 -- ---------------------------------------------------------------------------
467 #if defined(__GLASGOW_HASKELL__) || defined(__HUGS__)
468 fixIO :: (a -> IO a) -> IO a
470 ref <- newIORef (throw NonTermination)
471 ans <- unsafeInterleaveIO (readIORef ref)
473 writeIORef ref result
476 -- NOTE: we do our own explicit black holing here, because GHC's lazy
477 -- blackholing isn't enough. In an infinite loop, GHC may run the IO
478 -- computation a few times before it notices the loop, which is wrong.
482 -- Assume a unix platform, where text and binary I/O are identical.
483 openBinaryFile = openFile
484 hSetBinaryMode _ _ = return ()
489 -- | The function creates a temporary file in ReadWrite mode.
490 -- The created file isn\'t deleted automatically, so you need to delete it manually.
492 -- The file is creates with permissions such that only the current
493 -- user can read\/write it.
495 -- With some exceptions (see below), the file will be created securely
496 -- in the sense that an attacker should not be able to cause
497 -- openTempFile to overwrite another file on the filesystem using your
498 -- credentials, by putting symbolic links (on Unix) in the place where
499 -- the temporary file is to be created. On Unix the @O_CREAT@ and
500 -- @O_EXCL@ flags are used to prevent this attack, but note that
501 -- @O_EXCL@ is sometimes not supported on NFS filesystems, so if you
502 -- rely on this behaviour it is best to use local filesystems only.
504 openTempFile :: FilePath -- ^ Directory in which to create the file
505 -> String -- ^ File name template. If the template is \"foo.ext\" then
506 -- the created file will be \"fooXXX.ext\" where XXX is some
508 -> IO (FilePath, Handle)
509 openTempFile tmp_dir template
510 = openTempFile' "openTempFile" tmp_dir template False 0o600
512 -- | Like 'openTempFile', but opens the file in binary mode. See 'openBinaryFile' for more comments.
513 openBinaryTempFile :: FilePath -> String -> IO (FilePath, Handle)
514 openBinaryTempFile tmp_dir template
515 = openTempFile' "openBinaryTempFile" tmp_dir template True 0o600
517 -- | Like 'openTempFile', but uses the default file permissions
518 openTempFileWithDefaultPermissions :: FilePath -> String
519 -> IO (FilePath, Handle)
520 openTempFileWithDefaultPermissions tmp_dir template
521 = openTempFile' "openBinaryTempFile" tmp_dir template False 0o666
523 -- | Like 'openBinaryTempFile', but uses the default file permissions
524 openBinaryTempFileWithDefaultPermissions :: FilePath -> String
525 -> IO (FilePath, Handle)
526 openBinaryTempFileWithDefaultPermissions tmp_dir template
527 = openTempFile' "openBinaryTempFile" tmp_dir template True 0o666
529 openTempFile' :: String -> FilePath -> String -> Bool -> CMode
530 -> IO (FilePath, Handle)
531 openTempFile' loc tmp_dir template binary mode = do
535 -- We split off the last extension, so we can use .foo.ext files
536 -- for temporary files (hidden on Unix OSes). Unfortunately we're
537 -- below filepath in the hierarchy here.
539 case break (== '.') $ reverse template of
540 -- First case: template contains no '.'s. Just re-reverse it.
541 (rev_suffix, "") -> (reverse rev_suffix, "")
542 -- Second case: template contains at least one '.'. Strip the
543 -- dot from the prefix and prepend it to the suffix (if we don't
544 -- do this, the unique number will get added after the '.' and
545 -- thus be part of the extension, which is wrong.)
546 (rev_suffix, '.':rest) -> (reverse rest, '.':reverse rev_suffix)
547 -- Otherwise, something is wrong, because (break (== '.')) should
548 -- always return a pair with either the empty string or a string
549 -- beginning with '.' as the second component.
550 _ -> error "bug in System.IO.openTempFile"
553 oflags1 = rw_flags .|. o_EXCL
559 oflags = oflags1 .|. binary_flags
563 findTempName x = do h <- openFile filepath ReadWriteMode
565 #elif defined(__GLASGOW_HASKELL__)
567 fd <- withFilePath filepath $ \ f ->
573 then findTempName (x+1)
574 else ioError (errnoToIOError loc errno Nothing (Just tmp_dir))
577 (fD,fd_type) <- FD.mkFD fd ReadWriteMode Nothing{-no stat-}
581 h <- mkHandleFromFD fD fd_type filepath ReadWriteMode False{-set non-block-}
582 (Just localeEncoding)
586 h <- fdToHandle fd `onException` c_close fd
591 filename = prefix ++ show x ++ suffix
592 filepath = tmp_dir `combine` filename
594 -- XXX bits copied from System.FilePath, since that's not available here
598 | last a == pathSeparator = a ++ b
599 | otherwise = a ++ [pathSeparator] ++ b
602 fdToHandle fd = openFd (fromIntegral fd) False ReadWriteMode binary
605 -- XXX Should use filepath library
606 pathSeparator :: Char
607 #ifdef mingw32_HOST_OS
614 -- XXX Copied from GHC.Handle
615 std_flags, output_flags, rw_flags :: CInt
616 std_flags = o_NONBLOCK .|. o_NOCTTY
617 output_flags = std_flags .|. o_CREAT
618 rw_flags = output_flags .|. o_RDWR
622 foreign import ccall "getpid" c_getpid :: IO Int
626 -- Implementations should enforce as far as possible, at least locally to the
627 -- Haskell process, multiple-reader single-writer locking on files.
628 -- 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
629 -- open or semi-closed handle is managing a file for output, no new
630 -- handle can be allocated for that file. If any open or semi-closed
631 -- handle is managing a file for input, new handles can only be allocated
632 -- if they do not manage output. Whether two files are the same is
633 -- implementation-dependent, but they should normally be the same if they
634 -- have the same absolute path name and neither has been renamed, for
637 -- /Warning/: the 'readFile' operation holds a semi-closed handle on
638 -- the file until the entire contents of the file have been consumed.
639 -- It follows that an attempt to write to a file (using 'writeFile', for
640 -- example) that was earlier opened by 'readFile' will usually result in
641 -- failure with 'System.IO.Error.isAlreadyInUseError'.