remove instances for types/classes that are not part of Haskell
[haskell-report.git] / report / libs / System-IO.tex
1 \haddockmoduleheading{System.IO}
2 \label{module:System.IO}
3 \haddockbeginheader
4 {\haddockverb\begin{verbatim}
5 module System.IO (
6 IO, fixIO, FilePath, Handle, stdin, stdout, stderr, withFile,
7 openFile, IOMode(ReadMode, WriteMode, AppendMode, ReadWriteMode), hClose,
8 readFile, writeFile, appendFile, hFileSize, hSetFileSize, hIsEOF,
9 isEOF, BufferMode(NoBuffering, LineBuffering, BlockBuffering),
10 hSetBuffering, hGetBuffering, hFlush, hGetPosn, hSetPosn, HandlePosn,
11 hSeek, SeekMode(AbsoluteSeek, RelativeSeek, SeekFromEnd), hTell,
12 hIsOpen, hIsClosed, hIsReadable, hIsWritable, hIsSeekable,
13 hIsTerminalDevice, hSetEcho, hGetEcho, hShow, hWaitForInput, hReady,
14 hGetChar, hGetLine, hLookAhead, hGetContents, hPutChar, hPutStr,
15 hPutStrLn, hPrint, interact, putChar, putStr, putStrLn, print,
16 getChar, getLine, getContents, readIO, readLn
17 ) where\end{verbatim}}
18 \haddockendheader
19
20 \section{The IO monad
21 }
22 \begin{haddockdesc}
23 \item[\begin{tabular}{@{}l}
24 data\ IO\ a
25 \end{tabular}]\haddockbegindoc
26 A value of type \haddocktt{IO\ a} is a computation which, when performed,
27 does some I/O before returning a value of type \haddocktt{a}.
28 \par
29 There is really only one way to "perform" an I/O action: bind it to
30 \haddocktt{Main.main} in your program. When your program is run, the I/O will
31 be performed. It isn't possible to perform I/O from an arbitrary
32 function, unless that function is itself in the \haddockid{IO} monad and called
33 at some point, directly or indirectly, from \haddocktt{Main.main}.
34 \par
35 \haddockid{IO} is a monad, so \haddockid{IO} actions can be combined using either the do-notation
36 or the \haddocktt{>>} and \haddocktt{>>=} operations from the \haddocktt{Monad} class.
37 \par
38
39 \end{haddockdesc}
40 \begin{haddockdesc}
41 \item[\begin{tabular}{@{}l}
42 instance\ Monad\ IO\\instance\ Functor\ IO
43 \end{tabular}]
44 \end{haddockdesc}
45 \begin{haddockdesc}
46 \item[
47 fixIO\ ::\ (a\ ->\ IO\ a)\ ->\ IO\ a
48 ]
49 \end{haddockdesc}
50 \section{Files and handles
51 }
52 \begin{haddockdesc}
53 \item[\begin{tabular}{@{}l}
54 type\ FilePath\ =\ String
55 \end{tabular}]\haddockbegindoc
56 File and directory names are values of type \haddockid{String}, whose precise
57 meaning is operating system dependent. Files can be opened, yielding a
58 handle which can then be used to operate on the contents of that file.
59 \par
60
61 \end{haddockdesc}
62 \begin{haddockdesc}
63 \item[\begin{tabular}{@{}l}
64 data\ Handle
65 \end{tabular}]\haddockbegindoc
66 Haskell defines operations to read and write characters from and to files,
67 represented by values of type \haddocktt{Handle}. Each value of this type is a
68 \emph{handle}: a record used by the Haskell run-time system to \emph{manage} I/O
69 with file system objects. A handle has at least the following properties:
70 \par
71 \begin{itemize}
72 \item
73 whether it manages input or output or both;
74 \par
75
76 \item
77 whether it is \emph{open}, \emph{closed} or \emph{semi-closed};
78 \par
79
80 \item
81 whether the object is seekable;
82 \par
83
84 \item
85 whether buffering is disabled, or enabled on a line or block basis;
86 \par
87
88 \item
89 a buffer (whose length may be zero).
90 \par
91
92 \end{itemize}
93 Most handles will also have a current I/O position indicating where the next
94 input or output operation will occur. A handle is \emph{readable} if it
95 manages only input or both input and output; likewise, it is \emph{writable} if
96 it manages only output or both input and output. A handle is \emph{open} when
97 first allocated.
98 Once it is closed it can no longer be used for either input or output,
99 though an implementation cannot re-use its storage while references
100 remain to it. Handles are in the \haddockid{Show} and \haddockid{Eq} classes. The string
101 produced by showing a handle is system dependent; it should include
102 enough information to identify the handle for debugging. A handle is
103 equal according to \haddockid{==} only to itself; no attempt
104 is made to compare the internal state of different handles for equality.
105 \par
106
107 \end{haddockdesc}
108 \begin{haddockdesc}
109 \item[\begin{tabular}{@{}l}
110 instance\ Eq\ Handle\\instance\ Show\ Handle\\
111 \end{tabular}]
112 \end{haddockdesc}
113 \subsection{Standard handles
114 }
115 Three handles are allocated during program initialisation,
116 and are initially open.
117 \par
118
119 \begin{haddockdesc}
120 \item[\begin{tabular}{@{}l}
121 stdin\ ::\ Handle
122 \end{tabular}]\haddockbegindoc
123 A handle managing input from the Haskell program's standard input channel.
124 \par
125
126 \end{haddockdesc}
127 \begin{haddockdesc}
128 \item[\begin{tabular}{@{}l}
129 stdout\ ::\ Handle
130 \end{tabular}]\haddockbegindoc
131 A handle managing output to the Haskell program's standard output channel.
132 \par
133
134 \end{haddockdesc}
135 \begin{haddockdesc}
136 \item[\begin{tabular}{@{}l}
137 stderr\ ::\ Handle
138 \end{tabular}]\haddockbegindoc
139 A handle managing output to the Haskell program's standard error channel.
140 \par
141
142 \end{haddockdesc}
143 \section{Opening and closing files
144 }
145 \subsection{Opening files
146 }
147 \begin{haddockdesc}
148 \item[\begin{tabular}{@{}l}
149 withFile\ ::\ FilePath\ ->\ IOMode\ ->\ (Handle\ ->\ IO\ r)\ ->\ IO\ r
150 \end{tabular}]\haddockbegindoc
151 \haddocktt{withFile\ name\ mode\ act} opens a file using \haddockid{openFile} and passes
152 the resulting handle to the computation \haddocktt{act}. The handle will be
153 closed on exit from \haddockid{withFile}, whether by normal termination or by
154 raising an exception.
155 \par
156
157 \end{haddockdesc}
158 \begin{haddockdesc}
159 \item[\begin{tabular}{@{}l}
160 openFile\ ::\ FilePath\ ->\ IOMode\ ->\ IO\ Handle
161 \end{tabular}]\haddockbegindoc
162 Computation \haddockid{openFile} \haddocktt{file\ mode} allocates and returns a new, open
163 handle to manage the file \haddocktt{file}. It manages input if \haddocktt{mode}
164 is \haddockid{ReadMode}, output if \haddocktt{mode} is \haddockid{WriteMode} or \haddockid{AppendMode},
165 and both input and output if mode is \haddockid{ReadWriteMode}.
166 \par
167 If the file does not exist and it is opened for output, it should be
168 created as a new file. If \haddocktt{mode} is \haddockid{WriteMode} and the file
169 already exists, then it should be truncated to zero length.
170 Some operating systems delete empty files, so there is no guarantee
171 that the file will exist following an \haddockid{openFile} with \haddocktt{mode}
172 \haddockid{WriteMode} unless it is subsequently written to successfully.
173 The handle is positioned at the end of the file if \haddocktt{mode} is
174 \haddockid{AppendMode}, and otherwise at the beginning (in which case its
175 internal position is 0).
176 The initial buffer mode is implementation-dependent.
177 \par
178 This operation may fail with:
179 \par
180 \begin{itemize}
181 \item
182 \haddocktt{isAlreadyInUseError} if the file is already open and cannot be reopened;
183 \par
184
185 \item
186 \haddocktt{isDoesNotExistError} if the file does not exist; or
187 \par
188
189 \item
190 \haddocktt{isPermissionError} if the user does not have permission to open the file.
191 \par
192
193 \end{itemize}
194
195 \end{haddockdesc}
196 \begin{haddockdesc}
197 \item[\begin{tabular}{@{}l}
198 data\ IOMode
199 \end{tabular}]\haddockbegindoc
200 \haddockbeginconstrs
201 \haddockdecltt{=} & \haddockdecltt{ReadMode} & \\
202 \haddockdecltt{|} & \haddockdecltt{WriteMode} & \\
203 \haddockdecltt{|} & \haddockdecltt{AppendMode} & \\
204 \haddockdecltt{|} & \haddockdecltt{ReadWriteMode} & \\
205 \end{tabulary}\par
206 See \haddocktt{System.IO.openFile}
207 \par
208
209 \end{haddockdesc}
210 \begin{haddockdesc}
211 \item[\begin{tabular}{@{}l}
212 instance\ Enum\ IOMode\\instance\ Eq\ IOMode\\instance\ Ord\ IOMode\\instance\ Read\ IOMode\\instance\ Show\ IOMode\\instance\ Ix\ IOMode
213 \end{tabular}]
214 \end{haddockdesc}
215 \subsection{Closing files
216 }
217 \begin{haddockdesc}
218 \item[\begin{tabular}{@{}l}
219 hClose\ ::\ Handle\ ->\ IO\ ()
220 \end{tabular}]\haddockbegindoc
221 Computation \haddockid{hClose} \haddocktt{hdl} makes handle \haddocktt{hdl} closed. Before the
222 computation finishes, if \haddocktt{hdl} is writable its buffer is flushed as
223 for \haddockid{hFlush}.
224 Performing \haddockid{hClose} on a handle that has already been closed has no effect;
225 doing so is not an error. All other operations on a closed handle will fail.
226 If \haddockid{hClose} fails for any reason, any further operations (apart from
227 \haddockid{hClose}) on the handle will still fail as if \haddocktt{hdl} had been successfully
228 closed.
229 \par
230
231 \end{haddockdesc}
232 \subsection{Special cases
233 }
234 These functions are also exported by the \haddocktt{Prelude}.
235 \par
236
237 \begin{haddockdesc}
238 \item[\begin{tabular}{@{}l}
239 readFile\ ::\ FilePath\ ->\ IO\ String
240 \end{tabular}]\haddockbegindoc
241 The \haddockid{readFile} function reads a file and
242 returns the contents of the file as a string.
243 The file is read lazily, on demand, as with \haddockid{getContents}.
244 \par
245
246 \end{haddockdesc}
247 \begin{haddockdesc}
248 \item[\begin{tabular}{@{}l}
249 writeFile\ ::\ FilePath\ ->\ String\ ->\ IO\ ()
250 \end{tabular}]\haddockbegindoc
251 The computation \haddockid{writeFile} \haddocktt{file\ str} function writes the string \haddocktt{str},
252 to the file \haddocktt{file}.
253 \par
254
255 \end{haddockdesc}
256 \begin{haddockdesc}
257 \item[\begin{tabular}{@{}l}
258 appendFile\ ::\ FilePath\ ->\ String\ ->\ IO\ ()
259 \end{tabular}]\haddockbegindoc
260 The computation \haddockid{appendFile} \haddocktt{file\ str} function appends the string \haddocktt{str},
261 to the file \haddocktt{file}.
262 \par
263 Note that \haddockid{writeFile} and \haddockid{appendFile} write a literal string
264 to a file. To write a value of any printable type, as with \haddockid{print},
265 use the \haddockid{show} function to convert the value to a string first.
266 \par
267 \begin{quote}
268 {\haddockverb\begin{verbatim}
269 main = appendFile "squares" (show [(x,x*x) | x <- [0,0.1..2]])
270 \end{verbatim}}
271 \end{quote}
272
273 \end{haddockdesc}
274 \subsection{File locking
275 }
276 Implementations should enforce as far as possible, at least locally to the
277 Haskell process, multiple-reader single-writer locking on files.
278 That is, \emph{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
279 open or semi-closed handle is managing a file for output, no new
280 handle can be allocated for that file. If any open or semi-closed
281 handle is managing a file for input, new handles can only be allocated
282 if they do not manage output. Whether two files are the same is
283 implementation-dependent, but they should normally be the same if they
284 have the same absolute path name and neither has been renamed, for
285 example.
286 \par
287 \emph{Warning}: the \haddockid{readFile} operation holds a semi-closed handle on
288 the file until the entire contents of the file have been consumed.
289 It follows that an attempt to write to a file (using \haddockid{writeFile}, for
290 example) that was earlier opened by \haddockid{readFile} will usually result in
291 failure with \haddocktt{System.IO.Error.isAlreadyInUseError}.
292 \par
293
294 \section{Operations on handles
295 }
296 \subsection{Determining and changing the size of a file
297 }
298 \begin{haddockdesc}
299 \item[\begin{tabular}{@{}l}
300 hFileSize\ ::\ Handle\ ->\ IO\ Integer
301 \end{tabular}]\haddockbegindoc
302 For a handle \haddocktt{hdl} which attached to a physical file,
303 \haddockid{hFileSize} \haddocktt{hdl} returns the size of that file in 8-bit bytes.
304 \par
305
306 \end{haddockdesc}
307 \begin{haddockdesc}
308 \item[\begin{tabular}{@{}l}
309 hSetFileSize\ ::\ Handle\ ->\ Integer\ ->\ IO\ ()
310 \end{tabular}]\haddockbegindoc
311 \haddockid{hSetFileSize} \haddocktt{hdl} \haddocktt{size} truncates the physical file with handle \haddocktt{hdl} to \haddocktt{size} bytes.
312 \par
313
314 \end{haddockdesc}
315 \subsection{Detecting the end of input
316 }
317 \begin{haddockdesc}
318 \item[\begin{tabular}{@{}l}
319 hIsEOF\ ::\ Handle\ ->\ IO\ Bool
320 \end{tabular}]\haddockbegindoc
321 For a readable handle \haddocktt{hdl}, \haddockid{hIsEOF} \haddocktt{hdl} returns
322 \haddockid{True} if no further input can be taken from \haddocktt{hdl} or for a
323 physical file, if the current I/O position is equal to the length of
324 the file. Otherwise, it returns \haddockid{False}.
325 \par
326 NOTE: \haddockid{hIsEOF} may block, because it has to attempt to read from
327 the stream to determine whether there is any more data to be read.
328 \par
329
330 \end{haddockdesc}
331 \begin{haddockdesc}
332 \item[\begin{tabular}{@{}l}
333 isEOF\ ::\ IO\ Bool
334 \end{tabular}]\haddockbegindoc
335 The computation \haddockid{isEOF} is identical to \haddockid{hIsEOF},
336 except that it works only on \haddockid{stdin}.
337 \par
338
339 \end{haddockdesc}
340 \subsection{Buffering operations
341 }
342 \begin{haddockdesc}
343 \item[\begin{tabular}{@{}l}
344 data\ BufferMode
345 \end{tabular}]\haddockbegindoc
346 \haddockbeginconstrs
347 \haddockdecltt{=} & \haddockdecltt{NoBuffering} & buffering is disabled if possible.
348 \\
349 \haddockdecltt{|} & \haddockdecltt{LineBuffering} & line-buffering should be enabled if possible.
350 \\
351 \haddockdecltt{|} & \haddockdecltt{BlockBuffering (Maybe Int)} & block-buffering should be enabled if possible.
352 The size of the buffer is \haddocktt{n} items if the argument
353 is \haddockid{Just} \haddocktt{n} and is otherwise implementation-dependent.
354 \\
355 \end{tabulary}\par
356 Three kinds of buffering are supported: line-buffering,
357 block-buffering or no-buffering. These modes have the following
358 effects. For output, items are written out, or \emph{flushed},
359 from the internal buffer according to the buffer mode:
360 \par
361 \begin{itemize}
362 \item
363 \emph{line-buffering}: the entire output buffer is flushed
364 whenever a newline is output, the buffer overflows,
365 a \haddocktt{System.IO.hFlush} is issued, or the handle is closed.
366 \par
367
368 \item
369 \emph{block-buffering}: the entire buffer is written out whenever it
370 overflows, a \haddocktt{System.IO.hFlush} is issued, or the handle is closed.
371 \par
372
373 \item
374 \emph{no-buffering}: output is written immediately, and never stored
375 in the buffer.
376 \par
377
378 \end{itemize}
379 An implementation is free to flush the buffer more frequently,
380 but not less frequently, than specified above.
381 The output buffer is emptied as soon as it has been written out.
382 \par
383 Similarly, input occurs according to the buffer mode for the handle:
384 \par
385 \begin{itemize}
386 \item
387 \emph{line-buffering}: when the buffer for the handle is not empty,
388 the next item is obtained from the buffer; otherwise, when the
389 buffer is empty, characters up to and including the next newline
390 character are read into the buffer. No characters are available
391 until the newline character is available or the buffer is full.
392 \par
393
394 \item
395 \emph{block-buffering}: when the buffer for the handle becomes empty,
396 the next block of data is read into the buffer.
397 \par
398
399 \item
400 \emph{no-buffering}: the next input item is read and returned.
401 The \haddocktt{System.IO.hLookAhead} operation implies that even a no-buffered
402 handle may require a one-character buffer.
403 \par
404
405 \end{itemize}
406 The default buffering mode when a handle is opened is
407 implementation-dependent and may depend on the file system object
408 which is attached to that handle.
409 For most implementations, physical files will normally be block-buffered
410 and terminals will normally be line-buffered.
411 \par
412
413 \end{haddockdesc}
414 \begin{haddockdesc}
415 \item[\begin{tabular}{@{}l}
416 instance\ Eq\ BufferMode\\instance\ Ord\ BufferMode\\instance\ Read\ BufferMode\\instance\ Show\ BufferMode
417 \end{tabular}]
418 \end{haddockdesc}
419 \begin{haddockdesc}
420 \item[\begin{tabular}{@{}l}
421 hSetBuffering\ ::\ Handle\ ->\ BufferMode\ ->\ IO\ ()
422 \end{tabular}]\haddockbegindoc
423 Computation \haddockid{hSetBuffering} \haddocktt{hdl\ mode} sets the mode of buffering for
424 handle \haddocktt{hdl} on subsequent reads and writes.
425 \par
426 If the buffer mode is changed from \haddockid{BlockBuffering} or
427 \haddockid{LineBuffering} to \haddockid{NoBuffering}, then
428 \par
429 \begin{itemize}
430 \item
431 if \haddocktt{hdl} is writable, the buffer is flushed as for \haddockid{hFlush};
432 \par
433
434 \item
435 if \haddocktt{hdl} is not writable, the contents of the buffer is discarded.
436 \par
437
438 \end{itemize}
439 This operation may fail with:
440 \par
441 \begin{itemize}
442 \item
443 \haddocktt{isPermissionError} if the handle has already been used for reading
444 or writing and the implementation does not allow the buffering mode
445 to be changed.
446 \par
447
448 \end{itemize}
449
450 \end{haddockdesc}
451 \begin{haddockdesc}
452 \item[\begin{tabular}{@{}l}
453 hGetBuffering\ ::\ Handle\ ->\ IO\ BufferMode
454 \end{tabular}]\haddockbegindoc
455 Computation \haddockid{hGetBuffering} \haddocktt{hdl} returns the current buffering mode
456 for \haddocktt{hdl}.
457 \par
458
459 \end{haddockdesc}
460 \begin{haddockdesc}
461 \item[\begin{tabular}{@{}l}
462 hFlush\ ::\ Handle\ ->\ IO\ ()
463 \end{tabular}]\haddockbegindoc
464 The action \haddockid{hFlush} \haddocktt{hdl} causes any items buffered for output
465 in handle \haddocktt{hdl} to be sent immediately to the operating system.
466 \par
467 This operation may fail with:
468 \par
469 \begin{itemize}
470 \item
471 \haddocktt{isFullError} if the device is full;
472 \par
473
474 \item
475 \haddocktt{isPermissionError} if a system resource limit would be exceeded.
476 It is unspecified whether the characters in the buffer are discarded
477 or retained under these circumstances.
478 \par
479
480 \end{itemize}
481
482 \end{haddockdesc}
483 \subsection{Repositioning handles
484 }
485 \begin{haddockdesc}
486 \item[\begin{tabular}{@{}l}
487 hGetPosn\ ::\ Handle\ ->\ IO\ HandlePosn
488 \end{tabular}]\haddockbegindoc
489 Computation \haddockid{hGetPosn} \haddocktt{hdl} returns the current I/O position of
490 \haddocktt{hdl} as a value of the abstract type \haddockid{HandlePosn}.
491 \par
492
493 \end{haddockdesc}
494 \begin{haddockdesc}
495 \item[\begin{tabular}{@{}l}
496 hSetPosn\ ::\ HandlePosn\ ->\ IO\ ()
497 \end{tabular}]\haddockbegindoc
498 If a call to \haddockid{hGetPosn} \haddocktt{hdl} returns a position \haddocktt{p},
499 then computation \haddockid{hSetPosn} \haddocktt{p} sets the position of \haddocktt{hdl}
500 to the position it held at the time of the call to \haddockid{hGetPosn}.
501 \par
502 This operation may fail with:
503 \par
504 \begin{itemize}
505 \item
506 \haddocktt{isPermissionError} if a system resource limit would be exceeded.
507 \par
508
509 \end{itemize}
510
511 \end{haddockdesc}
512 \begin{haddockdesc}
513 \item[\begin{tabular}{@{}l}
514 data\ HandlePosn
515 \end{tabular}]
516 \end{haddockdesc}
517 \begin{haddockdesc}
518 \item[\begin{tabular}{@{}l}
519 instance\ Eq\ HandlePosn\\instance\ Show\ HandlePosn
520 \end{tabular}]
521 \end{haddockdesc}
522 \begin{haddockdesc}
523 \item[\begin{tabular}{@{}l}
524 hSeek\ ::\ Handle\ ->\ SeekMode\ ->\ Integer\ ->\ IO\ ()
525 \end{tabular}]\haddockbegindoc
526 Computation \haddockid{hSeek} \haddocktt{hdl\ mode\ i} sets the position of handle
527 \haddocktt{hdl} depending on \haddocktt{mode}.
528 The offset \haddocktt{i} is given in terms of 8-bit bytes.
529 \par
530 If \haddocktt{hdl} is block- or line-buffered, then seeking to a position which is not
531 in the current buffer will first cause any items in the output buffer to be
532 written to the device, and then cause the input buffer to be discarded.
533 Some handles may not be seekable (see \haddockid{hIsSeekable}), or only support a
534 subset of the possible positioning operations (for instance, it may only
535 be possible to seek to the end of a tape, or to a positive offset from
536 the beginning or current position).
537 It is not possible to set a negative I/O position, or for
538 a physical file, an I/O position beyond the current end-of-file.
539 \par
540 This operation may fail with:
541 \par
542 \begin{itemize}
543 \item
544 \haddocktt{isIllegalOperationError} if the Handle is not seekable, or does
545 not support the requested seek mode.
546 * \haddocktt{isPermissionError} if a system resource limit would be exceeded.
547 \par
548
549 \end{itemize}
550
551 \end{haddockdesc}
552 \begin{haddockdesc}
553 \item[\begin{tabular}{@{}l}
554 data\ SeekMode
555 \end{tabular}]\haddockbegindoc
556 \haddockbeginconstrs
557 \haddockdecltt{=} & \haddockdecltt{AbsoluteSeek} & the position of \haddocktt{hdl} is set to \haddocktt{i}.
558 \\
559 \haddockdecltt{|} & \haddockdecltt{RelativeSeek} & the position of \haddocktt{hdl} is set to offset \haddocktt{i}
560 from the current position.
561 \\
562 \haddockdecltt{|} & \haddockdecltt{SeekFromEnd} & the position of \haddocktt{hdl} is set to offset \haddocktt{i}
563 from the end of the file.
564 \\
565 \end{tabulary}\par
566 A mode that determines the effect of \haddocktt{hSeek} \haddocktt{hdl\ mode\ i}.
567 \par
568
569 \end{haddockdesc}
570 \begin{haddockdesc}
571 \item[\begin{tabular}{@{}l}
572 instance\ Enum\ SeekMode\\instance\ Eq\ SeekMode\\instance\ Ord\ SeekMode\\instance\ Read\ SeekMode\\instance\ Show\ SeekMode\\instance\ Ix\ SeekMode
573 \end{tabular}]
574 \end{haddockdesc}
575 \begin{haddockdesc}
576 \item[\begin{tabular}{@{}l}
577 hTell\ ::\ Handle\ ->\ IO\ Integer
578 \end{tabular}]\haddockbegindoc
579 Computation \haddockid{hTell} \haddocktt{hdl} returns the current position of the
580 handle \haddocktt{hdl}, as the number of bytes from the beginning of
581 the file. The value returned may be subsequently passed to
582 \haddockid{hSeek} to reposition the handle to the current position.
583 \par
584 This operation may fail with:
585 \par
586 \begin{itemize}
587 \item
588 \haddocktt{isIllegalOperationError} if the Handle is not seekable.
589 \par
590
591 \end{itemize}
592
593 \end{haddockdesc}
594 \subsection{Handle properties
595 }
596 Each of these operations returns \haddockid{True} if the handle has the
597 the specified property, or \haddockid{False} otherwise.
598 \par
599
600 \begin{haddockdesc}
601 \item[
602 hIsOpen\ ::\ Handle\ ->\ IO\ Bool
603 ]
604 \item[
605 hIsClosed\ ::\ Handle\ ->\ IO\ Bool
606 ]
607 \item[
608 hIsReadable\ ::\ Handle\ ->\ IO\ Bool
609 ]
610 \item[
611 hIsWritable\ ::\ Handle\ ->\ IO\ Bool
612 ]
613 \item[
614 hIsSeekable\ ::\ Handle\ ->\ IO\ Bool
615 ]
616 \end{haddockdesc}
617 \subsection{Terminal operations
618 }
619 \begin{haddockdesc}
620 \item[\begin{tabular}{@{}l}
621 hIsTerminalDevice\ ::\ Handle\ ->\ IO\ Bool
622 \end{tabular}]\haddockbegindoc
623 Is the handle connected to a terminal?
624 \par
625
626 \end{haddockdesc}
627 \begin{haddockdesc}
628 \item[\begin{tabular}{@{}l}
629 hSetEcho\ ::\ Handle\ ->\ Bool\ ->\ IO\ ()
630 \end{tabular}]\haddockbegindoc
631 Set the echoing status of a handle connected to a terminal.
632 \par
633
634 \end{haddockdesc}
635 \begin{haddockdesc}
636 \item[\begin{tabular}{@{}l}
637 hGetEcho\ ::\ Handle\ ->\ IO\ Bool
638 \end{tabular}]\haddockbegindoc
639 Get the echoing status of a handle connected to a terminal.
640 \par
641
642 \end{haddockdesc}
643 \subsection{Showing handle state
644 }
645 \begin{haddockdesc}
646 \item[\begin{tabular}{@{}l}
647 hShow\ ::\ Handle\ ->\ IO\ String
648 \end{tabular}]\haddockbegindoc
649 \haddockid{hShow} is in the \haddockid{IO} monad, and gives more comprehensive output
650 than the (pure) instance of \haddockid{Show} for \haddockid{Handle}.
651 \par
652
653 \end{haddockdesc}
654 \section{Text input and output
655 }
656 \subsection{Text input
657 }
658 \begin{haddockdesc}
659 \item[\begin{tabular}{@{}l}
660 hWaitForInput\ ::\ Handle\ ->\ Int\ ->\ IO\ Bool
661 \end{tabular}]\haddockbegindoc
662 Computation \haddockid{hWaitForInput} \haddocktt{hdl\ t}
663 waits until input is available on handle \haddocktt{hdl}.
664 It returns \haddockid{True} as soon as input is available on \haddocktt{hdl},
665 or \haddockid{False} if no input is available within \haddocktt{t} milliseconds. Note that
666 \haddockid{hWaitForInput} waits until one or more full \emph{characters} are available,
667 which means that it needs to do decoding, and hence may fail
668 with a decoding error.
669 \par
670 If \haddocktt{t} is less than zero, then \haddocktt{hWaitForInput} waits indefinitely.
671 \par
672 This operation may fail with:
673 \par
674 \begin{itemize}
675 \item
676 \haddocktt{isEOFError} if the end of file has been reached.
677 \par
678
679 \item
680 a decoding error, if the input begins with an invalid byte sequence
681 in this Handle's encoding.
682 \par
683
684 \end{itemize}
685
686 \end{haddockdesc}
687 \begin{haddockdesc}
688 \item[\begin{tabular}{@{}l}
689 hReady\ ::\ Handle\ ->\ IO\ Bool
690 \end{tabular}]\haddockbegindoc
691 Computation \haddockid{hReady} \haddocktt{hdl} indicates whether at least one item is
692 available for input from handle \haddocktt{hdl}.
693 \par
694 This operation may fail with:
695 \par
696 \begin{itemize}
697 \item
698 \haddocktt{System.IO.Error.isEOFError} if the end of file has been reached.
699 \par
700
701 \end{itemize}
702
703 \end{haddockdesc}
704 \begin{haddockdesc}
705 \item[\begin{tabular}{@{}l}
706 hGetChar\ ::\ Handle\ ->\ IO\ Char
707 \end{tabular}]\haddockbegindoc
708 Computation \haddockid{hGetChar} \haddocktt{hdl} reads a character from the file or
709 channel managed by \haddocktt{hdl}, blocking until a character is available.
710 \par
711 This operation may fail with:
712 \par
713 \begin{itemize}
714 \item
715 \haddockid{isEOFError} if the end of file has been reached.
716 \par
717
718 \end{itemize}
719
720 \end{haddockdesc}
721 \begin{haddockdesc}
722 \item[\begin{tabular}{@{}l}
723 hGetLine\ ::\ Handle\ ->\ IO\ String
724 \end{tabular}]\haddockbegindoc
725 Computation \haddockid{hGetLine} \haddocktt{hdl} reads a line from the file or
726 channel managed by \haddocktt{hdl}.
727 \par
728 This operation may fail with:
729 \par
730 \begin{itemize}
731 \item
732 \haddockid{isEOFError} if the end of file is encountered when reading
733 the \emph{first} character of the line.
734 \par
735
736 \end{itemize}
737 If \haddockid{hGetLine} encounters end-of-file at any other point while reading
738 in a line, it is treated as a line terminator and the (partial)
739 line is returned.
740 \par
741
742 \end{haddockdesc}
743 \begin{haddockdesc}
744 \item[\begin{tabular}{@{}l}
745 hLookAhead\ ::\ Handle\ ->\ IO\ Char
746 \end{tabular}]\haddockbegindoc
747 Computation \haddockid{hLookAhead} returns the next character from the handle
748 without removing it from the input buffer, blocking until a character
749 is available.
750 \par
751 This operation may fail with:
752 \par
753 \begin{itemize}
754 \item
755 \haddocktt{isEOFError} if the end of file has been reached.
756 \par
757
758 \end{itemize}
759
760 \end{haddockdesc}
761 \begin{haddockdesc}
762 \item[\begin{tabular}{@{}l}
763 hGetContents\ ::\ Handle\ ->\ IO\ String
764 \end{tabular}]\haddockbegindoc
765 Computation \haddockid{hGetContents} \haddocktt{hdl} returns the list of characters
766 corresponding to the unread portion of the channel or file managed
767 by \haddocktt{hdl}, which is put into an intermediate state, \emph{semi-closed}.
768 In this state, \haddocktt{hdl} is effectively closed,
769 but items are read from \haddocktt{hdl} on demand and accumulated in a special
770 list returned by \haddockid{hGetContents} \haddocktt{hdl}.
771 \par
772 Any operation that fails because a handle is closed,
773 also fails if a handle is semi-closed. The only exception is \haddocktt{hClose}.
774 A semi-closed handle becomes closed:
775 \par
776 \begin{itemize}
777 \item
778 if \haddocktt{hClose} is applied to it;
779 \par
780
781 \item
782 if an I/O error occurs when reading an item from the handle;
783 \par
784
785 \item
786 or once the entire contents of the handle has been read.
787 \par
788
789 \end{itemize}
790 Once a semi-closed handle becomes closed, the contents of the
791 associated list becomes fixed. The contents of this final list is
792 only partially specified: it will contain at least all the items of
793 the stream that were evaluated prior to the handle becoming closed.
794 \par
795 Any I/O errors encountered while a handle is semi-closed are simply
796 discarded.
797 \par
798 This operation may fail with:
799 \par
800 \begin{itemize}
801 \item
802 \haddockid{isEOFError} if the end of file has been reached.
803 \par
804
805 \end{itemize}
806
807 \end{haddockdesc}
808 \subsection{Text output
809 }
810 \begin{haddockdesc}
811 \item[\begin{tabular}{@{}l}
812 hPutChar\ ::\ Handle\ ->\ Char\ ->\ IO\ ()
813 \end{tabular}]\haddockbegindoc
814 Computation \haddockid{hPutChar} \haddocktt{hdl\ ch} writes the character \haddocktt{ch} to the
815 file or channel managed by \haddocktt{hdl}. Characters may be buffered if
816 buffering is enabled for \haddocktt{hdl}.
817 \par
818 This operation may fail with:
819 \par
820 \begin{itemize}
821 \item
822 \haddockid{isFullError} if the device is full; or
823 \par
824
825 \item
826 \haddockid{isPermissionError} if another system resource limit would be exceeded.
827 \par
828
829 \end{itemize}
830
831 \end{haddockdesc}
832 \begin{haddockdesc}
833 \item[\begin{tabular}{@{}l}
834 hPutStr\ ::\ Handle\ ->\ String\ ->\ IO\ ()
835 \end{tabular}]\haddockbegindoc
836 Computation \haddockid{hPutStr} \haddocktt{hdl\ s} writes the string
837 \haddocktt{s} to the file or channel managed by \haddocktt{hdl}.
838 \par
839 This operation may fail with:
840 \par
841 \begin{itemize}
842 \item
843 \haddockid{isFullError} if the device is full; or
844 \par
845
846 \item
847 \haddockid{isPermissionError} if another system resource limit would be exceeded.
848 \par
849
850 \end{itemize}
851
852 \end{haddockdesc}
853 \begin{haddockdesc}
854 \item[\begin{tabular}{@{}l}
855 hPutStrLn\ ::\ Handle\ ->\ String\ ->\ IO\ ()
856 \end{tabular}]\haddockbegindoc
857 The same as \haddockid{hPutStr}, but adds a newline character.
858 \par
859
860 \end{haddockdesc}
861 \begin{haddockdesc}
862 \item[\begin{tabular}{@{}l}
863 hPrint\ ::\ Show\ a\ =>\ Handle\ ->\ a\ ->\ IO\ ()
864 \end{tabular}]\haddockbegindoc
865 Computation \haddockid{hPrint} \haddocktt{hdl\ t} writes the string representation of \haddocktt{t}
866 given by the \haddockid{shows} function to the file or channel managed by \haddocktt{hdl}
867 and appends a newline.
868 \par
869 This operation may fail with:
870 \par
871 \begin{itemize}
872 \item
873 \haddocktt{System.IO.Error.isFullError} if the device is full; or
874 \par
875
876 \item
877 \haddocktt{System.IO.Error.isPermissionError} if another system resource limit would be exceeded.
878 \par
879
880 \end{itemize}
881
882 \end{haddockdesc}
883 \subsection{Special cases for standard input and output
884 }
885 These functions are also exported by the \haddocktt{Prelude}.
886 \par
887
888 \begin{haddockdesc}
889 \item[\begin{tabular}{@{}l}
890 interact\ ::\ (String\ ->\ String)\ ->\ IO\ ()
891 \end{tabular}]\haddockbegindoc
892 The \haddockid{interact} function takes a function of type \haddocktt{String->String}
893 as its argument. The entire input from the standard input device is
894 passed to this function as its argument, and the resulting string is
895 output on the standard output device.
896 \par
897
898 \end{haddockdesc}
899 \begin{haddockdesc}
900 \item[\begin{tabular}{@{}l}
901 putChar\ ::\ Char\ ->\ IO\ ()
902 \end{tabular}]\haddockbegindoc
903 Write a character to the standard output device
904 (same as \haddockid{hPutChar} \haddockid{stdout}).
905 \par
906
907 \end{haddockdesc}
908 \begin{haddockdesc}
909 \item[\begin{tabular}{@{}l}
910 putStr\ ::\ String\ ->\ IO\ ()
911 \end{tabular}]\haddockbegindoc
912 Write a string to the standard output device
913 (same as \haddockid{hPutStr} \haddockid{stdout}).
914 \par
915
916 \end{haddockdesc}
917 \begin{haddockdesc}
918 \item[\begin{tabular}{@{}l}
919 putStrLn\ ::\ String\ ->\ IO\ ()
920 \end{tabular}]\haddockbegindoc
921 The same as \haddockid{putStr}, but adds a newline character.
922 \par
923
924 \end{haddockdesc}
925 \begin{haddockdesc}
926 \item[\begin{tabular}{@{}l}
927 print\ ::\ Show\ a\ =>\ a\ ->\ IO\ ()
928 \end{tabular}]\haddockbegindoc
929 The \haddockid{print} function outputs a value of any printable type to the
930 standard output device.
931 Printable types are those that are instances of class \haddockid{Show}; \haddockid{print}
932 converts values to strings for output using the \haddockid{show} operation and
933 adds a newline.
934 \par
935 For example, a program to print the first 20 integers and their
936 powers of 2 could be written as:
937 \par
938 \begin{quote}
939 {\haddockverb\begin{verbatim}
940 main = print ([(n, 2^n) | n <- [0..19]])
941 \end{verbatim}}
942 \end{quote}
943
944 \end{haddockdesc}
945 \begin{haddockdesc}
946 \item[\begin{tabular}{@{}l}
947 getChar\ ::\ IO\ Char
948 \end{tabular}]\haddockbegindoc
949 Read a character from the standard input device
950 (same as \haddockid{hGetChar} \haddockid{stdin}).
951 \par
952
953 \end{haddockdesc}
954 \begin{haddockdesc}
955 \item[\begin{tabular}{@{}l}
956 getLine\ ::\ IO\ String
957 \end{tabular}]\haddockbegindoc
958 Read a line from the standard input device
959 (same as \haddockid{hGetLine} \haddockid{stdin}).
960 \par
961
962 \end{haddockdesc}
963 \begin{haddockdesc}
964 \item[\begin{tabular}{@{}l}
965 getContents\ ::\ IO\ String
966 \end{tabular}]\haddockbegindoc
967 The \haddockid{getContents} operation returns all user input as a single string,
968 which is read lazily as it is needed
969 (same as \haddockid{hGetContents} \haddockid{stdin}).
970 \par
971
972 \end{haddockdesc}
973 \begin{haddockdesc}
974 \item[\begin{tabular}{@{}l}
975 readIO\ ::\ Read\ a\ =>\ String\ ->\ IO\ a
976 \end{tabular}]\haddockbegindoc
977 The \haddockid{readIO} function is similar to \haddockid{read} except that it signals
978 parse failure to the \haddockid{IO} monad instead of terminating the program.
979 \par
980
981 \end{haddockdesc}
982 \begin{haddockdesc}
983 \item[\begin{tabular}{@{}l}
984 readLn\ ::\ Read\ a\ =>\ IO\ a
985 \end{tabular}]\haddockbegindoc
986 The \haddockid{readLn} function combines \haddockid{getLine} and \haddockid{readIO}.
987 \par
988
989 \end{haddockdesc}