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 -- ** Standard handles
30 -- | Three handles are allocated during program initialisation,
31 -- and are initially open.
33 stdin, stdout, stderr, -- :: Handle
35 -- * Opening and closing files
40 openFile, -- :: FilePath -> IOMode -> IO Handle
41 IOMode(ReadMode,WriteMode,AppendMode,ReadWriteMode),
45 hClose, -- :: Handle -> IO ()
49 -- | These functions are also exported by the "Prelude".
51 readFile, -- :: FilePath -> IO String
52 writeFile, -- :: FilePath -> String -> IO ()
53 appendFile, -- :: FilePath -> String -> IO ()
59 -- * Operations on handles
61 -- ** Determining and changing the size of a file
63 hFileSize, -- :: Handle -> IO Integer
64 #ifdef __GLASGOW_HASKELL__
65 hSetFileSize, -- :: Handle -> Integer -> IO ()
68 -- ** Detecting the end of input
70 hIsEOF, -- :: Handle -> IO Bool
73 -- ** Buffering operations
75 BufferMode(NoBuffering,LineBuffering,BlockBuffering),
76 hSetBuffering, -- :: Handle -> BufferMode -> IO ()
77 hGetBuffering, -- :: Handle -> IO BufferMode
78 hFlush, -- :: Handle -> IO ()
80 -- ** Repositioning handles
82 hGetPosn, -- :: Handle -> IO HandlePosn
83 hSetPosn, -- :: HandlePosn -> IO ()
84 HandlePosn, -- abstract, instance of: Eq, Show.
86 hSeek, -- :: Handle -> SeekMode -> Integer -> IO ()
87 SeekMode(AbsoluteSeek,RelativeSeek,SeekFromEnd),
89 hTell, -- :: Handle -> IO Integer
92 -- ** Handle properties
94 hIsOpen, hIsClosed, -- :: Handle -> IO Bool
95 hIsReadable, hIsWritable, -- :: Handle -> IO Bool
96 hIsSeekable, -- :: Handle -> IO Bool
98 -- ** Terminal operations (not portable: GHC\/Hugs only)
100 #if !defined(__NHC__)
101 hIsTerminalDevice, -- :: Handle -> IO Bool
103 hSetEcho, -- :: Handle -> Bool -> IO ()
104 hGetEcho, -- :: Handle -> IO Bool
107 -- ** Showing handle state (not portable: GHC only)
109 #ifdef __GLASGOW_HASKELL__
110 hShow, -- :: Handle -> IO String
113 -- * Text input and output
117 hWaitForInput, -- :: Handle -> Int -> IO Bool
118 hReady, -- :: Handle -> IO Bool
119 hGetChar, -- :: Handle -> IO Char
120 hGetLine, -- :: Handle -> IO [Char]
121 hLookAhead, -- :: Handle -> IO Char
122 hGetContents, -- :: Handle -> IO [Char]
126 hPutChar, -- :: Handle -> Char -> IO ()
127 hPutStr, -- :: Handle -> [Char] -> IO ()
128 hPutStrLn, -- :: Handle -> [Char] -> IO ()
129 hPrint, -- :: Show a => Handle -> a -> IO ()
131 -- ** Special cases for standard input and output
133 -- | These functions are also exported by the "Prelude".
135 interact, -- :: (String -> String) -> IO ()
136 putChar, -- :: Char -> IO ()
137 putStr, -- :: String -> IO ()
138 putStrLn, -- :: String -> IO ()
139 print, -- :: Show a => a -> IO ()
140 getChar, -- :: IO Char
141 getLine, -- :: IO String
142 getContents, -- :: IO String
143 readIO, -- :: Read a => String -> IO a
144 readLn, -- :: Read a => IO a
146 -- * Binary input and output
149 openBinaryFile, -- :: FilePath -> IOMode -> IO Handle
150 hSetBinaryMode, -- :: Handle -> Bool -> IO ()
151 hPutBuf, -- :: Handle -> Ptr a -> Int -> IO ()
152 hGetBuf, -- :: Handle -> Ptr a -> Int -> IO Int
153 #if !defined(__NHC__) && !defined(__HUGS__)
154 hPutBufNonBlocking, -- :: Handle -> Ptr a -> Int -> IO Int
155 hGetBufNonBlocking, -- :: Handle -> Ptr a -> Int -> IO Int
162 openTempFileWithDefaultPermissions,
163 openBinaryTempFileWithDefaultPermissions,
165 #if !defined(__NHC__) && !defined(__HUGS__)
166 -- * Unicode encoding\/decoding
168 -- | A text-mode 'Handle' has an associated 'TextEncoding', which
169 -- is used to decode bytes into Unicode characters when reading,
170 -- and encode Unicode characters into bytes when writing.
172 -- The default 'TextEncoding' is the same as the default encoding
173 -- on your system, which is also available as 'localeEncoding'.
174 -- (GHC note: on Windows, we currently do not support double-byte
175 -- encodings; if the console\'s code page is unsupported, then
176 -- 'localeEncoding' will be 'latin1'.)
178 -- Encoding and decoding errors are always detected and reported,
179 -- except during lazy I/O ('hGetContents', 'getContents', and
180 -- 'readFile'), where a decoding error merely results in
181 -- termination of the character stream, as with other I/O errors.
186 -- ** Unicode encodings
190 utf16, utf16le, utf16be,
191 utf32, utf32le, utf32be,
196 #if !defined(__NHC__) && !defined(__HUGS__)
197 -- * Newline conversion
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
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.
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.
214 -- Binary-mode 'Handle's do no newline translation at all.
217 Newline(..), nativeNewline,
219 noNewlineTranslation, universalNewlineMode, nativeNewlineMode,
223 import Control.Exception.Base
229 import Foreign.C.Error
230 import Foreign.C.Types
231 import System.Posix.Internals
232 import System.Posix.Types
235 #ifdef __GLASGOW_HASKELL__
237 import GHC.IO hiding ( onException )
239 import GHC.IO.Handle.FD
242 import GHC.IO.Exception ( userError )
243 import GHC.IO.Encoding
253 import System.IO.Unsafe ( unsafeInterleaveIO )
260 , IOMode (ReadMode,WriteMode,AppendMode,ReadWriteMode)
261 , BufferMode (NoBuffering,LineBuffering,BlockBuffering)
262 , SeekMode (AbsoluteSeek,RelativeSeek,SeekFromEnd)
263 , stdin, stdout, stderr
264 , openFile -- :: FilePath -> IOMode -> IO Handle
265 , hClose -- :: Handle -> IO ()
266 , hFileSize -- :: Handle -> IO Integer
267 , hIsEOF -- :: Handle -> IO Bool
268 , isEOF -- :: IO Bool
269 , hSetBuffering -- :: Handle -> BufferMode -> IO ()
270 , hGetBuffering -- :: Handle -> IO BufferMode
271 , hFlush -- :: Handle -> IO ()
272 , hGetPosn -- :: Handle -> IO HandlePosn
273 , hSetPosn -- :: HandlePosn -> IO ()
274 , hSeek -- :: Handle -> SeekMode -> Integer -> IO ()
275 , hWaitForInput -- :: Handle -> Int -> IO Bool
276 , hGetChar -- :: Handle -> IO Char
277 , hGetLine -- :: Handle -> IO [Char]
278 , hLookAhead -- :: Handle -> IO Char
279 , hGetContents -- :: Handle -> IO [Char]
280 , hPutChar -- :: Handle -> Char -> IO ()
281 , hPutStr -- :: Handle -> [Char] -> IO ()
282 , hPutStrLn -- :: Handle -> [Char] -> IO ()
283 , hPrint -- :: Handle -> [Char] -> IO ()
284 , hReady -- :: Handle -> [Char] -> IO ()
285 , hIsOpen, hIsClosed -- :: Handle -> IO Bool
286 , hIsReadable, hIsWritable -- :: Handle -> IO Bool
287 , hIsSeekable -- :: Handle -> IO Bool
291 , FilePath -- :: String
293 import NHC.IOExtras (fixIO, hPutBuf, hGetBuf)
297 -- -----------------------------------------------------------------------------
300 #ifdef __GLASGOW_HASKELL__
301 -- | Write a character to the standard output device
302 -- (same as 'hPutChar' 'stdout').
304 putChar :: Char -> IO ()
305 putChar c = hPutChar stdout c
307 -- | Write a string to the standard output device
308 -- (same as 'hPutStr' 'stdout').
310 putStr :: String -> IO ()
311 putStr s = hPutStr stdout s
313 -- | The same as 'putStr', but adds a newline character.
315 putStrLn :: String -> IO ()
316 putStrLn s = do putStr s
319 -- | The 'print' function outputs a value of any printable type to the
320 -- standard output device.
321 -- Printable types are those that are instances of class 'Show'; 'print'
322 -- converts values to strings for output using the 'show' operation and
325 -- For example, a program to print the first 20 integers and their
326 -- powers of 2 could be written as:
328 -- > main = print ([(n, 2^n) | n <- [0..19]])
330 print :: Show a => a -> IO ()
331 print x = putStrLn (show x)
333 -- | Read a character from the standard input device
334 -- (same as 'hGetChar' 'stdin').
337 getChar = hGetChar stdin
339 -- | Read a line from the standard input device
340 -- (same as 'hGetLine' 'stdin').
343 getLine = hGetLine stdin
345 -- | The 'getContents' operation returns all user input as a single string,
346 -- which is read lazily as it is needed
347 -- (same as 'hGetContents' 'stdin').
349 getContents :: IO String
350 getContents = hGetContents stdin
352 -- | The 'interact' function takes a function of type @String->String@
353 -- as its argument. The entire input from the standard input device is
354 -- passed to this function as its argument, and the resulting string is
355 -- output on the standard output device.
357 interact :: (String -> String) -> IO ()
358 interact f = do s <- getContents
361 -- | The 'readFile' function reads a file and
362 -- returns the contents of the file as a string.
363 -- The file is read lazily, on demand, as with 'getContents'.
365 readFile :: FilePath -> IO String
366 readFile name = openFile name ReadMode >>= hGetContents
368 -- | The computation 'writeFile' @file str@ function writes the string @str@,
369 -- to the file @file@.
370 writeFile :: FilePath -> String -> IO ()
371 writeFile f txt = withFile f WriteMode (\ hdl -> hPutStr hdl txt)
373 -- | The computation 'appendFile' @file str@ function appends the string @str@,
374 -- to the file @file@.
376 -- Note that 'writeFile' and 'appendFile' write a literal string
377 -- to a file. To write a value of any printable type, as with 'print',
378 -- use the 'show' function to convert the value to a string first.
380 -- > main = appendFile "squares" (show [(x,x*x) | x <- [0,0.1..2]])
382 appendFile :: FilePath -> String -> IO ()
383 appendFile f txt = withFile f AppendMode (\ hdl -> hPutStr hdl txt)
385 -- | The 'readLn' function combines 'getLine' and 'readIO'.
387 readLn :: Read a => IO a
388 readLn = do l <- getLine
392 -- | The 'readIO' function is similar to 'read' except that it signals
393 -- parse failure to the 'IO' monad instead of terminating the program.
395 readIO :: Read a => String -> IO a
396 readIO s = case (do { (x,t) <- reads s ;
400 [] -> ioError (userError "Prelude.readIO: no parse")
401 _ -> ioError (userError "Prelude.readIO: ambiguous parse")
402 #endif /* __GLASGOW_HASKELL__ */
405 -- | Computation 'hReady' @hdl@ indicates whether at least one item is
406 -- available for input from handle @hdl@.
408 -- This operation may fail with:
410 -- * 'System.IO.Error.isEOFError' if the end of file has been reached.
412 hReady :: Handle -> IO Bool
413 hReady h = hWaitForInput h 0
415 -- | The same as 'hPutStr', but adds a newline character.
417 hPutStrLn :: Handle -> String -> IO ()
418 hPutStrLn hndl str = do
422 -- | Computation 'hPrint' @hdl t@ writes the string representation of @t@
423 -- given by the 'shows' function to the file or channel managed by @hdl@
424 -- and appends a newline.
426 -- This operation may fail with:
428 -- * 'System.IO.Error.isFullError' if the device is full; or
430 -- * 'System.IO.Error.isPermissionError' if another system resource limit would be exceeded.
432 hPrint :: Show a => Handle -> a -> IO ()
433 hPrint hdl = hPutStrLn hdl . show
434 #endif /* !__NHC__ */
436 -- | @'withFile' name mode act@ opens a file using 'openFile' and passes
437 -- the resulting handle to the computation @act@. The handle will be
438 -- closed on exit from 'withFile', whether by normal termination or by
439 -- raising an exception.
440 withFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
441 withFile name mode = bracket (openFile name mode) hClose
443 -- | @'withBinaryFile' name mode act@ opens a file using 'openBinaryFile'
444 -- and passes the resulting handle to the computation @act@. The handle
445 -- will be closed on exit from 'withBinaryFile', whether by normal
446 -- termination or by raising an exception.
447 withBinaryFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
448 withBinaryFile name mode = bracket (openBinaryFile name mode) hClose
450 -- ---------------------------------------------------------------------------
453 #if defined(__GLASGOW_HASKELL__) || defined(__HUGS__)
454 fixIO :: (a -> IO a) -> IO a
456 ref <- newIORef (throw NonTermination)
457 ans <- unsafeInterleaveIO (readIORef ref)
459 writeIORef ref result
462 -- NOTE: we do our own explicit black holing here, because GHC's lazy
463 -- blackholing isn't enough. In an infinite loop, GHC may run the IO
464 -- computation a few times before it notices the loop, which is wrong.
468 -- Assume a unix platform, where text and binary I/O are identical.
469 openBinaryFile = openFile
470 hSetBinaryMode _ _ = return ()
473 -- | The function creates a temporary file in ReadWrite mode.
474 -- The created file isn\'t deleted automatically, so you need to delete it manually.
476 -- The file is creates with permissions such that only the current
477 -- user can read\/write it.
479 -- With some exceptions (see below), the file will be created securely
480 -- in the sense that an attacker should not be able to cause
481 -- openTempFile to overwrite another file on the filesystem using your
482 -- credentials, by putting symbolic links (on Unix) in the place where
483 -- the temporary file is to be created. On Unix the @O_CREAT@ and
484 -- @O_EXCL@ flags are used to prevent this attack, but note that
485 -- @O_EXCL@ is sometimes not supported on NFS filesystems, so if you
486 -- rely on this behaviour it is best to use local filesystems only.
488 openTempFile :: FilePath -- ^ Directory in which to create the file
489 -> String -- ^ File name template. If the template is \"foo.ext\" then
490 -- the created file will be \"fooXXX.ext\" where XXX is some
492 -> IO (FilePath, Handle)
493 openTempFile tmp_dir template
494 = openTempFile' "openTempFile" tmp_dir template False 0o600
496 -- | Like 'openTempFile', but opens the file in binary mode. See 'openBinaryFile' for more comments.
497 openBinaryTempFile :: FilePath -> String -> IO (FilePath, Handle)
498 openBinaryTempFile tmp_dir template
499 = openTempFile' "openBinaryTempFile" tmp_dir template True 0o600
501 -- | Like 'openTempFile', but uses the default file permissions
502 openTempFileWithDefaultPermissions :: FilePath -> String
503 -> IO (FilePath, Handle)
504 openTempFileWithDefaultPermissions tmp_dir template
505 = openTempFile' "openBinaryTempFile" tmp_dir template False 0o666
507 -- | Like 'openBinaryTempFile', but uses the default file permissions
508 openBinaryTempFileWithDefaultPermissions :: FilePath -> String
509 -> IO (FilePath, Handle)
510 openBinaryTempFileWithDefaultPermissions tmp_dir template
511 = openTempFile' "openBinaryTempFile" tmp_dir template True 0o666
513 openTempFile' :: String -> FilePath -> String -> Bool -> CMode
514 -> IO (FilePath, Handle)
515 openTempFile' loc tmp_dir template binary mode = do
519 -- We split off the last extension, so we can use .foo.ext files
520 -- for temporary files (hidden on Unix OSes). Unfortunately we're
521 -- below filepath in the hierarchy here.
523 case break (== '.') $ reverse template of
524 -- First case: template contains no '.'s. Just re-reverse it.
525 (rev_suffix, "") -> (reverse rev_suffix, "")
526 -- Second case: template contains at least one '.'. Strip the
527 -- dot from the prefix and prepend it to the suffix (if we don't
528 -- do this, the unique number will get added after the '.' and
529 -- thus be part of the extension, which is wrong.)
530 (rev_suffix, '.':rest) -> (reverse rest, '.':reverse rev_suffix)
531 -- Otherwise, something is wrong, because (break (== '.')) should
532 -- always return a pair with either the empty string or a string
533 -- beginning with '.' as the second component.
534 _ -> error "bug in System.IO.openTempFile"
537 oflags1 = rw_flags .|. o_EXCL
543 oflags = oflags1 .|. binary_flags
547 findTempName x = do h <- openFile filepath ReadWriteMode
551 fd <- withFilePath filepath $ \ f ->
557 then findTempName (x+1)
558 else ioError (errnoToIOError loc errno Nothing (Just tmp_dir))
560 -- XXX We want to tell fdToHandle what the filepath is,
561 -- as any exceptions etc will only be able to report the
563 h <- fdToHandle fd `onException` c_close fd
567 filename = prefix ++ show x ++ suffix
568 filepath = tmp_dir `combine` filename
570 -- XXX bits copied from System.FilePath, since that's not available here
574 | last a == pathSeparator = a ++ b
575 | otherwise = a ++ [pathSeparator] ++ b
578 fdToHandle fd = openFd (fromIntegral fd) False ReadWriteMode binary
581 -- XXX Should use filepath library
582 pathSeparator :: Char
583 #ifdef mingw32_HOST_OS
590 -- XXX Copied from GHC.Handle
591 std_flags, output_flags, rw_flags :: CInt
592 std_flags = o_NONBLOCK .|. o_NOCTTY
593 output_flags = std_flags .|. o_CREAT
594 rw_flags = output_flags .|. o_RDWR
598 foreign import ccall "getpid" c_getpid :: IO Int
602 -- Implementations should enforce as far as possible, at least locally to the
603 -- Haskell process, multiple-reader single-writer locking on files.
604 -- That is, /there may either be many handles on the same file which manage
605 -- input, or just one handle on the file which manages output/. If any
606 -- open or semi-closed handle is managing a file for output, no new
607 -- handle can be allocated for that file. If any open or semi-closed
608 -- handle is managing a file for input, new handles can only be allocated
609 -- if they do not manage output. Whether two files are the same is
610 -- implementation-dependent, but they should normally be the same if they
611 -- have the same absolute path name and neither has been renamed, for
614 -- /Warning/: the 'readFile' operation holds a semi-closed handle on
615 -- the file until the entire contents of the file have been consumed.
616 -- It follows that an attempt to write to a file (using 'writeFile', for
617 -- example) that was earlier opened by 'readFile' will usually result in
618 -- failure with 'System.IO.Error.isAlreadyInUseError'.