Copyright | (c) The University of Glasgow 1992-2008 |
---|---|
License | see libraries/base/LICENSE |
Maintainer | libraries@haskell.org |
Stability | internal |
Portability | non-portable |
Safe Haskell | Trustworthy |
Language | Haskell2010 |
String I/O functions
Synopsis
- hWaitForInput :: Handle -> Int -> IO Bool
- hGetChar :: Handle -> IO Char
- hGetLine :: Handle -> IO String
- hGetContents :: Handle -> IO String
- hPutChar :: Handle -> Char -> IO ()
- hPutStr :: Handle -> String -> IO ()
- commitBuffer' :: RawCharBuffer -> Int -> Int -> Bool -> Bool -> Handle__ -> IO CharBuffer
- hGetBuf :: Handle -> Ptr a -> Int -> IO Int
- hGetBufSome :: Handle -> Ptr a -> Int -> IO Int
- hGetBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int
- hPutBuf :: Handle -> Ptr a -> Int -> IO ()
- hPutBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int
- memcpy :: Ptr a -> Ptr a -> CSize -> IO (Ptr ())
- hPutStrLn :: Handle -> String -> IO ()
Documentation
hWaitForInput :: Handle -> Int -> IO Bool Source #
Computation hWaitForInput
hdl t
waits until input is available on handle hdl
.
It returns True
as soon as input is available on hdl
,
or False
if no input is available within t
milliseconds. Note that
hWaitForInput
waits until one or more full characters are available,
which means that it needs to do decoding, and hence may fail
with a decoding error.
If t
is less than zero, then hWaitForInput
waits indefinitely.
This operation may fail with:
isEOFError
if the end of file has been reached.- a decoding error, if the input begins with an invalid byte sequence in this Handle's encoding.
NOTE for GHC users: unless you use the -threaded
flag,
hWaitForInput hdl t
where t >= 0
will block all other Haskell
threads for the duration of the call. It behaves like a
safe
foreign call in this respect.
hGetChar :: Handle -> IO Char Source #
Computation hGetChar
hdl
reads a character from the file or
channel managed by hdl
, blocking until a character is available.
This operation may fail with:
isEOFError
if the end of file has been reached.
hGetLine :: Handle -> IO String Source #
Computation hGetLine
hdl
reads a line from the file or
channel managed by hdl
.
This operation may fail with:
isEOFError
if the end of file is encountered when reading the first character of the line.
If hGetLine
encounters end-of-file at any other point while reading
in a line, it is treated as a line terminator and the (partial)
line is returned.
hGetContents :: Handle -> IO String Source #
Computation hGetContents
hdl
returns the list of characters
corresponding to the unread portion of the channel or file managed
by hdl
, which is put into an intermediate state, semi-closed.
In this state, hdl
is effectively closed,
but items are read from hdl
on demand and accumulated in a special
list returned by hGetContents
hdl
.
Any operation that fails because a handle is closed,
also fails if a handle is semi-closed. The only exception is
hClose
. A semi-closed handle becomes closed:
- if
hClose
is applied to it; - if an I/O error occurs when reading an item from the handle;
- or once the entire contents of the handle has been read.
Once a semi-closed handle becomes closed, the contents of the associated list becomes fixed. The contents of this final list is only partially specified: it will contain at least all the items of the stream that were evaluated prior to the handle becoming closed.
Any I/O errors encountered while a handle is semi-closed are simply discarded.
This operation may fail with:
isEOFError
if the end of file has been reached.
hPutChar :: Handle -> Char -> IO () Source #
Computation hPutChar
hdl ch
writes the character ch
to the
file or channel managed by hdl
. Characters may be buffered if
buffering is enabled for hdl
.
This operation may fail with:
isFullError
if the device is full; orisPermissionError
if another system resource limit would be exceeded.
hPutStr :: Handle -> String -> IO () Source #
Computation hPutStr
hdl s
writes the string
s
to the file or channel managed by hdl
.
This operation may fail with:
isFullError
if the device is full; orisPermissionError
if another system resource limit would be exceeded.
commitBuffer' :: RawCharBuffer -> Int -> Int -> Bool -> Bool -> Handle__ -> IO CharBuffer Source #
hGetBuf :: Handle -> Ptr a -> Int -> IO Int Source #
hGetBuf
hdl buf count
reads data from the handle hdl
into the buffer buf
until either EOF is reached or
count
8-bit bytes have been read.
It returns the number of bytes actually read. This may be zero if
EOF was reached before any data was read (or if count
is zero).
hGetBuf
never raises an EOF exception, instead it returns a value
smaller than count
.
If the handle is a pipe or socket, and the writing end
is closed, hGetBuf
will behave as if EOF was reached.
hGetBuf
ignores the prevailing TextEncoding
and NewlineMode
on the Handle
, and reads bytes directly.
hGetBufSome :: Handle -> Ptr a -> Int -> IO Int Source #
hGetBufSome
hdl buf count
reads data from the handle hdl
into the buffer buf
. If there is any data available to read,
then hGetBufSome
returns it immediately; it only blocks if there
is no data to be read.
It returns the number of bytes actually read. This may be zero if
EOF was reached before any data was read (or if count
is zero).
hGetBufSome
never raises an EOF exception, instead it returns a value
smaller than count
.
If the handle is a pipe or socket, and the writing end
is closed, hGetBufSome
will behave as if EOF was reached.
hGetBufSome
ignores the prevailing TextEncoding
and
NewlineMode
on the Handle
, and reads bytes directly.
hGetBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int Source #
hGetBufNonBlocking
hdl buf count
reads data from the handle hdl
into the buffer buf
until either EOF is reached, or
count
8-bit bytes have been read, or there is no more data available
to read immediately.
hGetBufNonBlocking
is identical to hGetBuf
, except that it will
never block waiting for data to become available, instead it returns
only whatever data is available. To wait for data to arrive before
calling hGetBufNonBlocking
, use hWaitForInput
.
If the handle is a pipe or socket, and the writing end
is closed, hGetBufNonBlocking
will behave as if EOF was reached.
hGetBufNonBlocking
ignores the prevailing TextEncoding
and
NewlineMode
on the Handle
, and reads bytes directly.
NOTE: on Windows, this function does not work correctly; it
behaves identically to hGetBuf
.
hPutBuf :: Handle -> Ptr a -> Int -> IO () Source #
hPutBuf
hdl buf count
writes count
8-bit bytes from the
buffer buf
to the handle hdl
. It returns ().
hPutBuf
ignores any text encoding that applies to the Handle
,
writing the bytes directly to the underlying file or device.
hPutBuf
ignores the prevailing TextEncoding
and
NewlineMode
on the Handle
, and writes bytes directly.
This operation may fail with:
ResourceVanished
if the handle is a pipe or socket, and the reading end is closed. (If this is a POSIX system, and the program has not asked to ignore SIGPIPE, then a SIGPIPE may be delivered instead, whose default action is to terminate the program).