GHC.IO.Device

base-4.16.1.0: Basic libraries

Copyright | (c) The University of Glasgow 1994-2008
License | see libraries/base/LICENSE
Maintainer | libraries@haskell.org
Stability | internal
Portability | non-portable
Safe Haskell | Trustworthy
Language | Haskell2010

GHC.IO.Device

Description

Type classes for I/O providers.

Synopsis

- class RawIO a where
  - read :: a -> Ptr Word8 -> Word64 -> Int -> IO Int
  - readNonBlocking :: a -> Ptr Word8 -> Word64 -> Int -> IO (Maybe Int)
  - write :: a -> Ptr Word8 -> Word64 -> Int -> IO ()
  - writeNonBlocking :: a -> Ptr Word8 -> Word64 -> Int -> IO Int
- class IODevice a where
  - ready :: a -> Bool -> Int -> IO Bool
  - close :: a -> IO ()
  - isTerminal :: a -> IO Bool
  - isSeekable :: a -> IO Bool
  - seek :: a -> SeekMode -> Integer -> IO Integer
  - tell :: a -> IO Integer
  - getSize :: a -> IO Integer
  - setSize :: a -> Integer -> IO ()
  - setEcho :: a -> Bool -> IO ()
  - getEcho :: a -> IO Bool
  - setRaw :: a -> Bool -> IO ()
  - devType :: a -> IO IODeviceType
  - dup :: a -> IO a
  - dup2 :: a -> a -> IO a
- data IODeviceType
  - = Directory
  - | Stream
  - | RegularFile
  - | RawDevice
- data SeekMode
  - = AbsoluteSeek
  - | RelativeSeek
  - | SeekFromEnd

# Documentation

class RawIO a where Source #

A low-level I/O provider where the data is bytes in memory. The Word64 offsets currently have no effect on POSIX system or consoles where the implicit behaviour of the C runtime is assume to move the file pointer on every read/write without needing an explicit seek.

Methods

read :: a -> Ptr Word8 -> Word64 -> Int -> IO Int Source #

Read up to the specified number of bytes starting from a specified offset, returning the number of bytes actually read. This function should only block if there is no data available. If there is not enough data available, then the function should just return the available data. A return value of zero indicates that the end of the data stream (e.g. end of file) has been reached.

readNonBlocking :: a -> Ptr Word8 -> Word64 -> Int -> IO (Maybe Int) Source #

Read up to the specified number of bytes starting from a specified offset, returning the number of bytes actually read, or `Nothing` if the end of the stream has been reached.

write :: a -> Ptr Word8 -> Word64 -> Int -> IO () Source #

Write the specified number of bytes starting at a given offset.

writeNonBlocking :: a -> Ptr Word8 -> Word64 -> Int -> IO Int Source #

Write up to the specified number of bytes without blocking starting at a given offset. Returns the actual number of bytes written.

#### Instances

Instances details

RawIO FD Source # | Since: base-4.1.0.0
Instance details Defined in GHC.IO.FD Methods read :: FD -> Ptr Word8 -> Word64 -> Int -> IO Int Source # readNonBlocking :: FD -> Ptr Word8 -> Word64 -> Int -> IO (Maybe Int) Source # write :: FD -> Ptr Word8 -> Word64 -> Int -> IO () Source # writeNonBlocking :: FD -> Ptr Word8 -> Word64 -> Int -> IO Int Source #

class IODevice a where Source #

I/O operations required for implementing a `Handle`.

Minimal complete definition

ready, close, devType

Methods

ready :: a -> Bool -> Int -> IO Bool Source #

`ready dev write msecs` returns `True` if the device has data to read (if `write` is `False`) or space to write new data (if `write` is `True`). `msecs` specifies how long to wait, in milliseconds.

close :: a -> IO () Source #

closes the device. Further operations on the device should produce exceptions.

isTerminal :: a -> IO Bool Source #

returns `True` if the device is a terminal or console.

isSeekable :: a -> IO Bool Source #

returns `True` if the device supports `seek` operations.

seek :: a -> SeekMode -> Integer -> IO Integer Source #

seek to the specified position in the data.

tell :: a -> IO Integer Source #

return the current position in the data.

getSize :: a -> IO Integer Source #

return the size of the data.

setSize :: a -> Integer -> IO () Source #

change the size of the data.

setEcho :: a -> Bool -> IO () Source #

for terminal devices, changes whether characters are echoed on the device.

getEcho :: a -> IO Bool Source #

returns the current echoing status.

setRaw :: a -> Bool -> IO () Source #

some devices (e.g. terminals) support a "raw" mode where characters entered are immediately made available to the program. If available, this operations enables raw mode.

devType :: a -> IO IODeviceType Source #

returns the `IODeviceType` corresponding to this device.

dup :: a -> IO a Source #

duplicates the device, if possible. The new device is expected to share a file pointer with the original device (like Unix `dup`).

dup2 :: a -> a -> IO a Source #

`dup2 source target` replaces the target device with the source device. The target device is closed first, if necessary, and then it is made into a duplicate of the first device (like Unix `dup2`).

#### Instances

Instances details

IODevice FD Source # | Since: base-4.1.0.0
Instance details Defined in GHC.IO.FD Methods ready :: FD -> Bool -> Int -> IO Bool Source # close :: FD -> IO () Source # isTerminal :: FD -> IO Bool Source # isSeekable :: FD -> IO Bool Source # seek :: FD -> SeekMode -> Integer -> IO Integer Source # tell :: FD -> IO Integer Source # getSize :: FD -> IO Integer Source # setSize :: FD -> Integer -> IO () Source # setEcho :: FD -> Bool -> IO () Source # getEcho :: FD -> IO Bool Source # setRaw :: FD -> Bool -> IO () Source # devType :: FD -> IO IODeviceType Source # dup :: FD -> IO FD Source # dup2 :: FD -> FD -> IO FD Source #

data IODeviceType Source #

Type of a device that can be used to back a `Handle` (see also `mkFileHandle`). The standard libraries provide creation of `Handle`s via Posix file operations with file descriptors (see `mkHandleFromFD`) with FD being the underlying `IODevice` instance.

Users may provide custom instances of `IODevice` which are expected to conform the following rules:

Constructors

Directory | The standard libraries do not have direct support for this device type, but a user implementation is expected to provide a list of file names in the directory, in any order, separated by `'\0'` characters, excluding the `"."` and `".."` names. See also `getDirectoryContents`. Seek operations are not supported on directories (other than to the zero position).
Stream | A duplex communications channel (results in creation of a duplex `Handle`). The standard libraries use this device type when creating `Handle`s for open sockets.
RegularFile | A file that may be read or written, and also may be seekable.
RawDevice | A "raw" (disk) device which supports block binary read and write operations and may be seekable only to positions of certain granularity (block- aligned).

#### Instances

Instances details

Eq IODeviceType Source # | Since: base-4.2.0.0
Instance details Defined in GHC.IO.Device Methods (==) :: IODeviceType -> IODeviceType -> Bool Source # (/=) :: IODeviceType -> IODeviceType -> Bool Source #

data SeekMode Source #

A mode that determines the effect of `hSeek` `hdl mode i`.

Constructors

AbsoluteSeek | the position of `hdl` is set to `i`.
RelativeSeek | the position of `hdl` is set to offset `i` from the current position.
SeekFromEnd | the position of `hdl` is set to offset `i` from the end of the file.

#### Instances

Instances details

Enum SeekMode Source # | Since: base-4.2.0.0
Instance details Defined in GHC.IO.Device Methods succ :: SeekMode -> SeekMode Source # pred :: SeekMode -> SeekMode Source # toEnum :: Int -> SeekMode Source # fromEnum :: SeekMode -> Int Source # enumFrom :: SeekMode -> [SeekMode] Source # enumFromThen :: SeekMode -> SeekMode -> [SeekMode] Source # enumFromTo :: SeekMode -> SeekMode -> [SeekMode] Source # enumFromThenTo :: SeekMode -> SeekMode -> SeekMode -> [SeekMode] Source #
Ix SeekMode Source # | Since: base-4.2.0.0
Instance details Defined in GHC.IO.Device Methods range :: (SeekMode, SeekMode) -> [SeekMode] Source # index :: (SeekMode, SeekMode) -> SeekMode -> Int Source # unsafeIndex :: (SeekMode, SeekMode) -> SeekMode -> Int Source # inRange :: (SeekMode, SeekMode) -> SeekMode -> Bool Source # rangeSize :: (SeekMode, SeekMode) -> Int Source # unsafeRangeSize :: (SeekMode, SeekMode) -> Int Source #
Read SeekMode Source # | Since: base-4.2.0.0
Instance details Defined in GHC.IO.Device Methods readsPrec :: Int -> ReadS SeekMode Source # readList :: ReadS [SeekMode] Source # readPrec :: ReadPrec SeekMode Source # readListPrec :: ReadPrec [SeekMode] Source #
Show SeekMode Source # | Since: base-4.2.0.0
Instance details Defined in GHC.IO.Device Methods showsPrec :: Int -> SeekMode -> ShowS Source # show :: SeekMode -> String Source # showList :: [SeekMode] -> ShowS Source #
Eq SeekMode Source # | Since: base-4.2.0.0
Instance details Defined in GHC.IO.Device Methods (==) :: SeekMode -> SeekMode -> Bool Source # (/=) :: SeekMode -> SeekMode -> Bool Source #
Ord SeekMode Source # | Since: base-4.2.0.0
Instance details Defined in GHC.IO.Device Methods compare :: SeekMode -> SeekMode -> Ordering Source # (<) :: SeekMode -> SeekMode -> Bool Source # (<=) :: SeekMode -> SeekMode -> Bool Source # (>) :: SeekMode -> SeekMode -> Bool Source # (>=) :: SeekMode -> SeekMode -> Bool Source # max :: SeekMode -> SeekMode -> SeekMode Source # min :: SeekMode -> SeekMode -> SeekMode Source #