1 {-# LANGUAGE CPP, NoImplicitPrelude #-}
3 -----------------------------------------------------------------------------
6 -- Copyright : (c) The University of Glasgow 2001
7 -- License : BSD-style (see the file libraries/base/LICENSE)
9 -- Maintainer : libraries@haskell.org
11 -- Portability : portable
13 -- The standard IO library.
15 -----------------------------------------------------------------------------
20 IO, -- instance MonadFix
21 fixIO, -- :: (a -> IO a) -> IO a
23 -- * Files and handles
25 FilePath, -- :: String
27 Handle, -- abstract, instance of: Eq, Show.
29 -- | GHC note: a 'Handle' will be automatically closed when the garbage
30 -- collector detects that it has become unreferenced by the program.
31 -- However, relying on this behaviour is not generally recommended:
32 -- the garbage collector is unpredictable. If possible, use
33 -- an explicit 'hClose' to close 'Handle's when they are no longer
34 -- required. GHC does not currently attempt to free up file
35 -- descriptors when they have run out, it is your responsibility to
36 -- ensure that this doesn't happen.
38 -- ** Standard handles
40 -- | Three handles are allocated during program initialisation,
41 -- and are initially open.
43 stdin, stdout, stderr, -- :: Handle
45 -- * Opening and closing files
50 openFile, -- :: FilePath -> IOMode -> IO Handle
51 IOMode(ReadMode,WriteMode,AppendMode,ReadWriteMode),
55 hClose, -- :: Handle -> IO ()
59 -- | These functions are also exported by the "Prelude".
61 readFile, -- :: FilePath -> IO String
62 writeFile, -- :: FilePath -> String -> IO ()
63 appendFile, -- :: FilePath -> String -> IO ()
69 -- * Operations on handles
71 -- ** Determining and changing the size of a file
73 hFileSize, -- :: Handle -> IO Integer
74 #ifdef __GLASGOW_HASKELL__
75 hSetFileSize, -- :: Handle -> Integer -> IO ()
78 -- ** Detecting the end of input
80 hIsEOF, -- :: Handle -> IO Bool
83 -- ** Buffering operations
85 BufferMode(NoBuffering,LineBuffering,BlockBuffering),
86 hSetBuffering, -- :: Handle -> BufferMode -> IO ()
87 hGetBuffering, -- :: Handle -> IO BufferMode
88 hFlush, -- :: Handle -> IO ()
90 -- ** Repositioning handles
92 hGetPosn, -- :: Handle -> IO HandlePosn
93 hSetPosn, -- :: HandlePosn -> IO ()
94 HandlePosn, -- abstract, instance of: Eq, Show.
96 hSeek, -- :: Handle -> SeekMode -> Integer -> IO ()
97 SeekMode(AbsoluteSeek,RelativeSeek,SeekFromEnd),
99 hTell, -- :: Handle -> IO Integer
102 -- ** Handle properties
104 hIsOpen, hIsClosed, -- :: Handle -> IO Bool
105 hIsReadable, hIsWritable, -- :: Handle -> IO Bool
106 hIsSeekable, -- :: Handle -> IO Bool
108 -- ** Terminal operations (not portable: GHC\/Hugs only)
110 #if !defined(__NHC__)
111 hIsTerminalDevice, -- :: Handle -> IO Bool
113 hSetEcho, -- :: Handle -> Bool -> IO ()
114 hGetEcho, -- :: Handle -> IO Bool
117 -- ** Showing handle state (not portable: GHC only)
119 #ifdef __GLASGOW_HASKELL__
120 hShow, -- :: Handle -> IO String
123 -- * Text input and output
127 hWaitForInput, -- :: Handle -> Int -> IO Bool
128 hReady, -- :: Handle -> IO Bool
129 hGetChar, -- :: Handle -> IO Char
130 hGetLine, -- :: Handle -> IO [Char]
131 hLookAhead, -- :: Handle -> IO Char
132 hGetContents, -- :: Handle -> IO [Char]
136 hPutChar, -- :: Handle -> Char -> IO ()
137 hPutStr, -- :: Handle -> [Char] -> IO ()
138 hPutStrLn, -- :: Handle -> [Char] -> IO ()
139 hPrint, -- :: Show a => Handle -> a -> IO ()
141 -- ** Special cases for standard input and output
143 -- | These functions are also exported by the "Prelude".
145 interact, -- :: (String -> String) -> IO ()
146 putChar, -- :: Char -> IO ()
147 putStr, -- :: String -> IO ()
148 putStrLn, -- :: String -> IO ()
149 print, -- :: Show a => a -> IO ()
150 getChar, -- :: IO Char
151 getLine, -- :: IO String
152 getContents, -- :: IO String
153 readIO, -- :: Read a => String -> IO a
154 readLn, -- :: Read a => IO a
156 -- * Binary input and output
159 openBinaryFile, -- :: FilePath -> IOMode -> IO Handle
160 hSetBinaryMode, -- :: Handle -> Bool -> IO ()
161 hPutBuf, -- :: Handle -> Ptr a -> Int -> IO ()
162 hGetBuf, -- :: Handle -> Ptr a -> Int -> IO Int
163 #if !defined(__NHC__) && !defined(__HUGS__)
164 hGetBufSome, -- :: Handle -> Ptr a -> Int -> IO Int
165 hPutBufNonBlocking, -- :: Handle -> Ptr a -> Int -> IO Int
166 hGetBufNonBlocking, -- :: Handle -> Ptr a -> Int -> IO Int
173 openTempFileWithDefaultPermissions,
174 openBinaryTempFileWithDefaultPermissions,
176 #if !defined(__NHC__) && !defined(__HUGS__)
177 -- * Unicode encoding\/decoding
179 -- | A text-mode 'Handle' has an associated 'TextEncoding', which
180 -- is used to decode bytes into Unicode characters when reading,
181 -- and encode Unicode characters into bytes when writing.
183 -- The default 'TextEncoding' is the same as the default encoding
184 -- on your system, which is also available as 'localeEncoding'.
185 -- (GHC note: on Windows, we currently do not support double-byte
186 -- encodings; if the console\'s code page is unsupported, then
187 -- 'localeEncoding' will be 'latin1'.)
189 -- Encoding and decoding errors are always detected and reported,
190 -- except during lazy I/O ('hGetContents', 'getContents', and
191 -- 'readFile'), where a decoding error merely results in
192 -- termination of the character stream, as with other I/O errors.
197 -- ** Unicode encodings
201 utf16, utf16le, utf16be,
202 utf32, utf32le, utf32be,
207 #if !defined(__NHC__) && !defined(__HUGS__)
208 -- * Newline conversion
210 -- | In Haskell, a newline is always represented by the character
211 -- '\n'. However, in files and external character streams, a
212 -- newline may be represented by another character sequence, such
215 -- A text-mode 'Handle' has an associated 'NewlineMode' that
216 -- specifies how to transate newline characters. The
217 -- 'NewlineMode' specifies the input and output translation
218 -- separately, so that for instance you can translate '\r\n'
219 -- to '\n' on input, but leave newlines as '\n' on output.
221 -- The default 'NewlineMode' for a 'Handle' is
222 -- 'nativeNewlineMode', which does no translation on Unix systems,
223 -- but translates '\r\n' to '\n' and back on Windows.
225 -- Binary-mode 'Handle's do no newline translation at all.
228 Newline(..), nativeNewline,
230 noNewlineTranslation, universalNewlineMode, nativeNewlineMode,
234 import Control.Exception.Base
240 import Foreign.C.Error
241 import Foreign.C.Types
242 import System.Posix.Internals
243 import System.Posix.Types
246 #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, hPutStrLn )
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 = hPutStrLn stdout 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 -- | Computation 'hPrint' @hdl t@ writes the string representation of @t@
428 -- given by the 'shows' function to the file or channel managed by @hdl@
429 -- and appends a newline.
431 -- This operation may fail with:
433 -- * 'System.IO.Error.isFullError' if the device is full; or
435 -- * 'System.IO.Error.isPermissionError' if another system resource limit would be exceeded.
437 hPrint :: Show a => Handle -> a -> IO ()
438 hPrint hdl = hPutStrLn hdl . show
439 #endif /* !__NHC__ */
441 -- | @'withFile' name mode act@ opens a file using 'openFile' and passes
442 -- the resulting handle to the computation @act@. The handle will be
443 -- closed on exit from 'withFile', whether by normal termination or by
444 -- raising an exception. If closing the handle raises an exception, then
445 -- this exception will be raised by 'withFile' rather than any exception
447 withFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
448 withFile name mode = bracket (openFile name mode) hClose
450 -- | @'withBinaryFile' name mode act@ opens a file using 'openBinaryFile'
451 -- and passes the resulting handle to the computation @act@. The handle
452 -- will be closed on exit from 'withBinaryFile', whether by normal
453 -- termination or by raising an exception.
454 withBinaryFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
455 withBinaryFile name mode = bracket (openBinaryFile name mode) hClose
457 -- ---------------------------------------------------------------------------
460 #if defined(__GLASGOW_HASKELL__) || defined(__HUGS__)
461 fixIO :: (a -> IO a) -> IO a
463 ref <- newIORef (throw NonTermination)
464 ans <- unsafeInterleaveIO (readIORef ref)
466 writeIORef ref result
469 -- NOTE: we do our own explicit black holing here, because GHC's lazy
470 -- blackholing isn't enough. In an infinite loop, GHC may run the IO
471 -- computation a few times before it notices the loop, which is wrong.
475 -- Assume a unix platform, where text and binary I/O are identical.
476 openBinaryFile = openFile
477 hSetBinaryMode _ _ = return ()
482 -- | The function creates a temporary file in ReadWrite mode.
483 -- The created file isn\'t deleted automatically, so you need to delete it manually.
485 -- The file is creates with permissions such that only the current
486 -- user can read\/write it.
488 -- With some exceptions (see below), the file will be created securely
489 -- in the sense that an attacker should not be able to cause
490 -- openTempFile to overwrite another file on the filesystem using your
491 -- credentials, by putting symbolic links (on Unix) in the place where
492 -- the temporary file is to be created. On Unix the @O_CREAT@ and
493 -- @O_EXCL@ flags are used to prevent this attack, but note that
494 -- @O_EXCL@ is sometimes not supported on NFS filesystems, so if you
495 -- rely on this behaviour it is best to use local filesystems only.
497 openTempFile :: FilePath -- ^ Directory in which to create the file
498 -> String -- ^ File name template. If the template is \"foo.ext\" then
499 -- the created file will be \"fooXXX.ext\" where XXX is some
501 -> IO (FilePath, Handle)
502 openTempFile tmp_dir template
503 = openTempFile' "openTempFile" tmp_dir template False 0o600
505 -- | Like 'openTempFile', but opens the file in binary mode. See 'openBinaryFile' for more comments.
506 openBinaryTempFile :: FilePath -> String -> IO (FilePath, Handle)
507 openBinaryTempFile tmp_dir template
508 = openTempFile' "openBinaryTempFile" tmp_dir template True 0o600
510 -- | Like 'openTempFile', but uses the default file permissions
511 openTempFileWithDefaultPermissions :: FilePath -> String
512 -> IO (FilePath, Handle)
513 openTempFileWithDefaultPermissions tmp_dir template
514 = openTempFile' "openBinaryTempFile" tmp_dir template False 0o666
516 -- | Like 'openBinaryTempFile', but uses the default file permissions
517 openBinaryTempFileWithDefaultPermissions :: FilePath -> String
518 -> IO (FilePath, Handle)
519 openBinaryTempFileWithDefaultPermissions tmp_dir template
520 = openTempFile' "openBinaryTempFile" tmp_dir template True 0o666
522 openTempFile' :: String -> FilePath -> String -> Bool -> CMode
523 -> IO (FilePath, Handle)
524 openTempFile' loc tmp_dir template binary mode = do
528 -- We split off the last extension, so we can use .foo.ext files
529 -- for temporary files (hidden on Unix OSes). Unfortunately we're
530 -- below filepath in the hierarchy here.
532 case break (== '.') $ reverse template of
533 -- First case: template contains no '.'s. Just re-reverse it.
534 (rev_suffix, "") -> (reverse rev_suffix, "")
535 -- Second case: template contains at least one '.'. Strip the
536 -- dot from the prefix and prepend it to the suffix (if we don't
537 -- do this, the unique number will get added after the '.' and
538 -- thus be part of the extension, which is wrong.)
539 (rev_suffix, '.':rest) -> (reverse rest, '.':reverse rev_suffix)
540 -- Otherwise, something is wrong, because (break (== '.')) should
541 -- always return a pair with either the empty string or a string
542 -- beginning with '.' as the second component.
543 _ -> error "bug in System.IO.openTempFile"
546 oflags1 = rw_flags .|. o_EXCL
552 oflags = oflags1 .|. binary_flags
556 findTempName x = do h <- openFile filepath ReadWriteMode
558 #elif defined(__GLASGOW_HASKELL__)
560 fd <- withFilePath filepath $ \ f ->
566 then findTempName (x+1)
567 else ioError (errnoToIOError loc errno Nothing (Just tmp_dir))
570 (fD,fd_type) <- FD.mkFD fd ReadWriteMode Nothing{-no stat-}
574 h <- mkHandleFromFD fD fd_type filepath ReadWriteMode False{-set non-block-}
575 (Just localeEncoding)
579 h <- fdToHandle fd `onException` c_close fd
584 filename = prefix ++ show x ++ suffix
585 filepath = tmp_dir `combine` filename
587 -- XXX bits copied from System.FilePath, since that's not available here
591 | last a == pathSeparator = a ++ b
592 | otherwise = a ++ [pathSeparator] ++ b
595 fdToHandle fd = openFd (fromIntegral fd) False ReadWriteMode binary
598 -- XXX Should use filepath library
599 pathSeparator :: Char
600 #ifdef mingw32_HOST_OS
607 -- XXX Copied from GHC.Handle
608 std_flags, output_flags, rw_flags :: CInt
609 std_flags = o_NONBLOCK .|. o_NOCTTY
610 output_flags = std_flags .|. o_CREAT
611 rw_flags = output_flags .|. o_RDWR
615 foreign import ccall "getpid" c_getpid :: IO Int
619 -- Implementations should enforce as far as possible, at least locally to the
620 -- Haskell process, multiple-reader single-writer locking on files.
621 -- 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
622 -- open or semi-closed handle is managing a file for output, no new
623 -- handle can be allocated for that file. If any open or semi-closed
624 -- handle is managing a file for input, new handles can only be allocated
625 -- if they do not manage output. Whether two files are the same is
626 -- implementation-dependent, but they should normally be the same if they
627 -- have the same absolute path name and neither has been renamed, for
630 -- /Warning/: the 'readFile' operation holds a semi-closed handle on
631 -- the file until the entire contents of the file have been consumed.
632 -- It follows that an attempt to write to a file (using 'writeFile', for
633 -- example) that was earlier opened by 'readFile' will usually result in
634 -- failure with 'System.IO.Error.isAlreadyInUseError'.