unix-2.4.2.0: POSIX functionality

Portability | non-portable (requires POSIX)
Stability | provisional
Maintainer | libraries@haskell.org

System.Posix.IO

Contents

- Input / Output
  - Standard file descriptors
  - Opening and closing files
  - Reading/writing data
  - Seeking
  - File options
  - Locking
  - Pipes
  - Duplicating file descriptors
  - Converting file descriptors to/from Handles

Description

POSIX IO support. These types and functions correspond to the unix functions open(2), close(2), etc. For more portable functions which are more like fopen(3) and friends from stdio.h, see System.IO.

Synopsis

- stdInput :: Fd
- stdOutput :: Fd
- stdError :: Fd
- data OpenMode
  - = ReadOnly
  - | WriteOnly
  - | ReadWrite
- data OpenFileFlags = OpenFileFlags {
  - append :: Bool
  - exclusive :: Bool
  - noctty :: Bool
  - nonBlock :: Bool
  - trunc :: Bool
  }
- defaultFileFlags :: OpenFileFlags
- openFd :: FilePath -> OpenMode -> Maybe FileMode -> OpenFileFlags -> IO Fd
- createFile :: FilePath -> FileMode -> IO Fd
- closeFd :: Fd -> IO ()
- fdRead :: Fd -> ByteCount -> IO (String, ByteCount)
- fdWrite :: Fd -> String -> IO ByteCount
- fdReadBuf :: Fd -> Ptr Word8 -> ByteCount -> IO ByteCount
- fdWriteBuf :: Fd -> Ptr Word8 -> ByteCount -> IO ByteCount
- fdSeek :: Fd -> SeekMode -> FileOffset -> IO FileOffset
- data FdOption
  - = AppendOnWrite
  - | CloseOnExec
  - | NonBlockingRead
  - | SynchronousWrites
- queryFdOption :: Fd -> FdOption -> IO Bool
- setFdOption :: Fd -> FdOption -> Bool -> IO ()
- type FileLock = (LockRequest, SeekMode, FileOffset, FileOffset)
- data LockRequest
  - = ReadLock
  - | WriteLock
  - | Unlock
- getLock :: Fd -> FileLock -> IO (Maybe (ProcessID, FileLock))
- setLock :: Fd -> FileLock -> IO ()
- waitToSetLock :: Fd -> FileLock -> IO ()
- createPipe :: IO (Fd, Fd)
- dup :: Fd -> IO Fd
- dupTo :: Fd -> Fd -> IO Fd
- handleToFd :: Handle -> IO Fd
- fdToHandle :: Fd -> IO Handle

# Input / Output

## Standard file descriptors

stdInput :: Fd Source

stdOutput :: Fd Source

stdError :: Fd Source

## Opening and closing files

data OpenMode Source

Constructors

ReadOnly |
WriteOnly |
ReadWrite |

data OpenFileFlags Source

Correspond to some of the int flags from C's fcntl.h.

Constructors

OpenFileFlags |

Fields

append :: Bool

  O_APPEND

exclusive :: Bool

  O_EXCL

noctty :: Bool

  O_NOCTTY

nonBlock :: Bool

  O_NONBLOCK

trunc :: Bool

  O_TRUNC

defaultFileFlags :: OpenFileFlags Source

Default values for the `OpenFileFlags` type. False for each of append, exclusive, noctty, nonBlock, and trunc.

openFdSource

Arguments

:: FilePath |
-> OpenMode |
-> Maybe FileMode | Just x => creates the file with the given modes, Nothing => the file must exist.
-> OpenFileFlags |
-> IO Fd |

Open and optionally create this file. See `System.Posix.Files` for information on how to use the `FileMode` type.

createFile :: FilePath -> FileMode -> IO Fd Source

Create and open this file in WriteOnly mode. A special case of `openFd`. See `System.Posix.Files` for information on how to use the `FileMode` type.

closeFd :: Fd -> IO ()Source

Close this file descriptor. May throw an exception if this is an invalid descriptor.

## Reading/writing data

Programmers using the `fdRead` and `fdWrite` API should be aware that EAGAIN exceptions may occur for non-blocking IO!

fdReadSource

Arguments

:: Fd |
-> ByteCount | How many bytes to read
-> IO (String, ByteCount) | The bytes read, how many bytes were read.

Read data from an `Fd` and convert it to a `String`. Throws an exception if this is an invalid descriptor, or EOF has been reached.

fdWrite :: Fd -> String -> IO ByteCount Source

Write a `String` to an `Fd` (no character conversion is done, the least-significant 8 bits of each character are written).

fdReadBufSource

Arguments

:: Fd |
-> Ptr Word8 | Memory in which to put the data
-> ByteCount | Maximum number of bytes to read
-> IO ByteCount | Number of bytes read (zero for EOF)

Read data from an `Fd` into memory. This is exactly equivalent to the POSIX `read` function.

fdWriteBufSource

Arguments

:: Fd |
-> Ptr Word8 | Memory containing the data to write
-> ByteCount | Maximum number of bytes to write
-> IO ByteCount | Number of bytes written

Write data from memory to an `Fd`. This is exactly equivalent to the POSIX `write` function.

## Seeking

fdSeek :: Fd -> SeekMode -> FileOffset -> IO FileOffset Source

May throw an exception if this is an invalid descriptor.

## File options

data FdOption Source

Constructors

AppendOnWrite | O_APPEND
CloseOnExec | FD_CLOEXEC
NonBlockingRead | O_NONBLOCK
SynchronousWrites | O_SYNC

queryFdOption :: Fd -> FdOption -> IO Bool Source

May throw an exception if this is an invalid descriptor.

setFdOption :: Fd -> FdOption -> Bool -> IO ()Source

May throw an exception if this is an invalid descriptor.

## Locking

type FileLock = (LockRequest, SeekMode, FileOffset, FileOffset)Source

data LockRequest Source

Constructors

ReadLock |
WriteLock |
Unlock |

getLock :: Fd -> FileLock -> IO (Maybe (ProcessID, FileLock))Source

May throw an exception if this is an invalid descriptor.

setLock :: Fd -> FileLock -> IO ()Source

May throw an exception if this is an invalid descriptor.

waitToSetLock :: Fd -> FileLock -> IO ()Source

May throw an exception if this is an invalid descriptor.

## Pipes

createPipe :: IO (Fd, Fd)Source

The `createPipe` function creates a pair of connected file descriptors. The first component is the fd to read from, the second is the write end. Although pipes may be bidirectional, this behaviour is not portable and programmers should use two separate pipes for this purpose. May throw an exception if this is an invalid descriptor.

## Duplicating file descriptors

dup :: Fd -> IO Fd Source

May throw an exception if this is an invalid descriptor.

dupTo :: Fd -> Fd -> IO Fd Source

May throw an exception if this is an invalid descriptor.

## Converting file descriptors to/from Handles

handleToFd :: Handle -> IO Fd Source

Extracts the `Fd` from a `Handle`. This function has the side effect of closing the `Handle` and flushing its write buffer, if necessary.

fdToHandle :: Fd -> IO Handle Source

Converts an `Fd` into a `Handle` that can be used with the standard Haskell IO library (see System.IO).

GHC only: this function has the side effect of putting the `Fd` into non-blocking mode (`O_NONBLOCK`) due to the way the standard IO library implements multithreaded I/O.