1 {-# OPTIONS_GHC -fno-implicit-prelude -funbox-strict-fields #-}
2 {-# OPTIONS_HADDOCK hide #-}
3 -----------------------------------------------------------------------------
5 -- Module : GHC.IO.Handle.Types
6 -- Copyright : (c) The University of Glasgow, 1994-2009
7 -- License : see libraries/base/LICENSE
9 -- Maintainer : libraries@haskell.org
10 -- Stability : internal
11 -- Portability : non-portable
13 -- Basic types for the implementation of IO Handles.
15 -----------------------------------------------------------------------------
17 module GHC.IO.Handle.Types (
18 Handle(..), Handle__(..), showHandle,
19 checkHandleInvariants,
22 isReadableHandleType, isWritableHandleType, isReadWriteHandleType,
25 NewlineMode(..), Newline(..), nativeNewline,
26 universalNewlineMode, noNewlineTranslation, nativeNewlineMode
35 import GHC.IO.BufferedIO
36 import GHC.IO.Encoding.Types
45 -- ---------------------------------------------------------------------------
48 -- A Handle is represented by (a reference to) a record
49 -- containing the state of the I/O port/device. We record
50 -- the following pieces of info:
52 -- * type (read,write,closed etc.)
53 -- * the underlying file descriptor
55 -- * buffer, and spare buffers
56 -- * user-friendly name (usually the
57 -- FilePath used when IO.openFile was called)
59 -- Note: when a Handle is garbage collected, we want to flush its buffer
60 -- and close the OS file handle, so as to free up a (precious) resource.
62 -- | Haskell defines operations to read and write characters from and to files,
63 -- represented by values of type @Handle@. Each value of this type is a
64 -- /handle/: a record used by the Haskell run-time system to /manage/ I\/O
65 -- with file system objects. A handle has at least the following properties:
67 -- * whether it manages input or output or both;
69 -- * whether it is /open/, /closed/ or /semi-closed/;
71 -- * whether the object is seekable;
73 -- * whether buffering is disabled, or enabled on a line or block basis;
75 -- * a buffer (whose length may be zero).
77 -- Most handles will also have a current I\/O position indicating where the next
78 -- input or output operation will occur. A handle is /readable/ if it
79 -- manages only input or both input and output; likewise, it is /writable/ if
80 -- it manages only output or both input and output. A handle is /open/ when
82 -- Once it is closed it can no longer be used for either input or output,
83 -- though an implementation cannot re-use its storage while references
84 -- remain to it. Handles are in the 'Show' and 'Eq' classes. The string
85 -- produced by showing a handle is system dependent; it should include
86 -- enough information to identify the handle for debugging. A handle is
87 -- equal according to '==' only to itself; no attempt
88 -- is made to compare the internal state of different handles for equality.
90 -- GHC note: a 'Handle' will be automatically closed when the garbage
91 -- collector detects that it has become unreferenced by the program.
92 -- However, relying on this behaviour is not generally recommended:
93 -- the garbage collector is unpredictable. If possible, use explicit
94 -- an explicit 'hClose' to close 'Handle's when they are no longer
95 -- required. GHC does not currently attempt to free up file
96 -- descriptors when they have run out, it is your responsibility to
97 -- ensure that this doesn't happen.
100 = FileHandle -- A normal handle to a file
101 FilePath -- the file (used for error messages
105 | DuplexHandle -- A handle to a read/write stream
106 FilePath -- file for a FIFO, otherwise some
107 -- descriptive string (used for error
109 !(MVar Handle__) -- The read side
110 !(MVar Handle__) -- The write side
115 -- * A 'FileHandle' is seekable. A 'DuplexHandle' may or may not be
118 instance Eq Handle where
119 (FileHandle _ h1) == (FileHandle _ h2) = h1 == h2
120 (DuplexHandle _ h1 _) == (DuplexHandle _ h2 _) = h1 == h2
124 = forall dev enc_state dec_state . (IODevice dev, BufferedIO dev, Typeable dev) =>
127 haType :: HandleType, -- type (read/write/append etc.)
128 haByteBuffer :: !(IORef (Buffer Word8)),
129 haBufferMode :: BufferMode,
130 haLastDecode :: !(IORef (dec_state, Buffer Word8)),
131 haCharBuffer :: !(IORef (Buffer CharBufElem)), -- the current buffer
132 haBuffers :: !(IORef (BufferList CharBufElem)), -- spare buffers
133 haEncoder :: Maybe (TextEncoder enc_state),
134 haDecoder :: Maybe (TextDecoder dec_state),
135 haInputNL :: Newline,
136 haOutputNL :: Newline,
137 haOtherSide :: Maybe (MVar Handle__) -- ptr to the write side of a
142 -- we keep a few spare buffers around in a handle to avoid allocating
143 -- a new one for each hPutStr. These buffers are *guaranteed* to be the
144 -- same size as the main buffer.
147 | BufferListCons (RawBuffer e) (BufferList e)
149 -- Internally, we classify handles as being one
160 isReadableHandleType :: HandleType -> Bool
161 isReadableHandleType ReadHandle = True
162 isReadableHandleType ReadWriteHandle = True
163 isReadableHandleType _ = False
165 isWritableHandleType :: HandleType -> Bool
166 isWritableHandleType AppendHandle = True
167 isWritableHandleType WriteHandle = True
168 isWritableHandleType ReadWriteHandle = True
169 isWritableHandleType _ = False
171 isReadWriteHandleType :: HandleType -> Bool
172 isReadWriteHandleType ReadWriteHandle{} = True
173 isReadWriteHandleType _ = False
175 -- INVARIANTS on Handles:
177 -- * A handle *always* has a buffer, even if it is only 1 character long
178 -- (an unbuffered handle needs a 1 character buffer in order to support
179 -- hLookAhead and hIsEOF).
180 -- * In a read Handle, the byte buffer is always empty (we decode when reading)
181 -- * In a wriite Handle, the Char buffer is always empty (we encode when writing)
183 checkHandleInvariants :: Handle__ -> IO ()
185 checkHandleInvariants h_ = do
186 bbuf <- readIORef (haByteBuffer h_)
188 cbuf <- readIORef (haCharBuffer h_)
191 checkHandleInvariants _ = return ()
194 -- ---------------------------------------------------------------------------
197 -- | Three kinds of buffering are supported: line-buffering,
198 -- block-buffering or no-buffering. These modes have the following
199 -- effects. For output, items are written out, or /flushed/,
200 -- from the internal buffer according to the buffer mode:
202 -- * /line-buffering/: the entire output buffer is flushed
203 -- whenever a newline is output, the buffer overflows,
204 -- a 'System.IO.hFlush' is issued, or the handle is closed.
206 -- * /block-buffering/: the entire buffer is written out whenever it
207 -- overflows, a 'System.IO.hFlush' is issued, or the handle is closed.
209 -- * /no-buffering/: output is written immediately, and never stored
212 -- An implementation is free to flush the buffer more frequently,
213 -- but not less frequently, than specified above.
214 -- The output buffer is emptied as soon as it has been written out.
216 -- Similarly, input occurs according to the buffer mode for the handle:
218 -- * /line-buffering/: when the buffer for the handle is not empty,
219 -- the next item is obtained from the buffer; otherwise, when the
220 -- buffer is empty, characters up to and including the next newline
221 -- character are read into the buffer. No characters are available
222 -- until the newline character is available or the buffer is full.
224 -- * /block-buffering/: when the buffer for the handle becomes empty,
225 -- the next block of data is read into the buffer.
227 -- * /no-buffering/: the next input item is read and returned.
228 -- The 'System.IO.hLookAhead' operation implies that even a no-buffered
229 -- handle may require a one-character buffer.
231 -- The default buffering mode when a handle is opened is
232 -- implementation-dependent and may depend on the file system object
233 -- which is attached to that handle.
234 -- For most implementations, physical files will normally be block-buffered
235 -- and terminals will normally be line-buffered.
238 = NoBuffering -- ^ buffering is disabled if possible.
240 -- ^ line-buffering should be enabled if possible.
241 | BlockBuffering (Maybe Int)
242 -- ^ block-buffering should be enabled if possible.
243 -- The size of the buffer is @n@ items if the argument
244 -- is 'Just' @n@ and is otherwise implementation-dependent.
245 deriving (Eq, Ord, Read, Show)
248 [note Buffering Implementation]
250 Each Handle has two buffers: a byte buffer (haByteBuffer) and a Char
251 buffer (haCharBuffer).
253 [note Buffered Reading]
255 For read Handles, bytes are read into the byte buffer, and immediately
256 decoded into the Char buffer (see
257 GHC.IO.Handle.Internals.readTextDevice). The only way there might be
258 some data left in the byte buffer is if there is a partial multi-byte
259 character sequence that cannot be decoded into a full character.
261 Note that the buffering mode (haBufferMode) makes no difference when
262 reading data into a Handle. When reading, we can always just read all
263 the data there is available without blocking, decode it into the Char
264 buffer, and then provide it immediately to the caller.
266 [note Buffered Writing]
268 Characters are written into the Char buffer by e.g. hPutStr. When the
269 buffer is full, we call writeTextDevice, which encodes the Char buffer
270 into the byte buffer, and then immediately writes it all out to the
271 underlying device. The Char buffer will always be empty afterward.
272 This might require multiple decoding/writing cycles.
276 Since the buffer mode makes no difference when reading, we can just
277 use the default buffer size for both the byte and the Char buffer.
278 Ineed, we must have room for at least one Char in the Char buffer,
279 because we have to implement hLookAhead, which requires caching a Char
280 in the Handle. Furthermore, when doing newline translation, we need
281 room for at least two Chars in the read buffer, so we can spot the
284 For writing, however, when the buffer mode is NoBuffering, we use a
285 1-element Char buffer to force flushing of the buffer after each Char
288 [note Buffer Flushing]
290 ** Flushing the Char buffer
292 We must be able to flush the Char buffer, in order to implement
293 hSetEncoding, and things like hGetBuf which want to read raw bytes.
295 Flushing the Char buffer on a write Handle is easy: just call
296 writeTextDevice to encode and write the date.
298 Flushing the Char buffer on a read Handle involves rewinding the byte
299 buffer to the point representing the next Char in the Char buffer.
302 - remembering the state of the byte buffer *before* the last decode
304 - re-decoding the bytes that represent the chars already read from the
305 Char buffer. This gives us the point in the byte buffer that
306 represents the *next* Char to be read.
308 In order for this to work, after readTextHandle we must NOT MODIFY THE
309 CONTENTS OF THE BYTE OR CHAR BUFFERS, except to remove characters from
312 ** Flushing the byte buffer
314 The byte buffer can be flushed if the Char buffer has already been
315 flushed (see above). For a read Handle, flushing the byte buffer
316 means seeking the device back by the number of bytes in the buffer,
317 and hence it is only possible on a seekable Handle.
321 -- ---------------------------------------------------------------------------
322 -- Newline translation
324 -- | The representation of a newline in the external file or stream.
325 data Newline = LF -- ^ "\n"
329 -- | Specifies the translation, if any, of newline characters between
330 -- internal Strings and the external file or stream. Haskell Strings
331 -- are assumed to represent newlines with the '\n' character; the
332 -- newline mode specifies how to translate '\n' on output, and what to
333 -- translate into '\n' on input.
335 = NewlineMode { inputNL :: Newline,
336 -- ^ the representation of newlines on input
338 -- ^ the representation of newlines on output
342 -- | The native newline representation for the current platform
343 nativeNewline :: Newline
344 #ifdef mingw32_HOST_OS
350 -- | Map "\r\n" into "\n" on input, and "\n" to the native newline
351 -- represetnation on output. This mode can be used on any platform, and
352 -- works with text files using any newline convention. The downside is
353 -- that @readFile >>= writeFile@ might yield a different file.
355 -- > universalNewlineMode = NewlineMode { inputNL = CRLF,
356 -- > outputNL = nativeNewline }
358 universalNewlineMode :: NewlineMode
359 universalNewlineMode = NewlineMode { inputNL = CRLF,
360 outputNL = nativeNewline }
362 -- | Use the native newline representation on both input and output
364 -- > nativeNewlineMode = NewlineMode { inputNL = nativeNewline
365 -- > outputNL = nativeNewline }
367 nativeNewlineMode :: NewlineMode
368 nativeNewlineMode = NewlineMode { inputNL = nativeNewline,
369 outputNL = nativeNewline }
371 -- | Do no newline translation at all.
373 -- > noNewlineTranslation = NewlineMode { inputNL = LF, outputNL = LF }
375 noNewlineTranslation :: NewlineMode
376 noNewlineTranslation = NewlineMode { inputNL = LF, outputNL = LF }
378 -- ---------------------------------------------------------------------------
379 -- Show instance for Handles
381 -- handle types are 'show'n when printing error msgs, so
382 -- we provide a more user-friendly Show instance for it
383 -- than the derived one.
385 instance Show HandleType where
388 ClosedHandle -> showString "closed"
389 SemiClosedHandle -> showString "semi-closed"
390 ReadHandle -> showString "readable"
391 WriteHandle -> showString "writable"
392 AppendHandle -> showString "writable (append)"
393 ReadWriteHandle -> showString "read-writable"
395 instance Show Handle where
396 showsPrec _ (FileHandle file _) = showHandle file
397 showsPrec _ (DuplexHandle file _ _) = showHandle file
399 showHandle :: FilePath -> String -> String
400 showHandle file = showString "{handle: " . showString file . showString "}"