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

stdOutput :: Fd

stdError :: Fd

## Opening and closing files

data OpenMode

Constructors

ReadOnly |
WriteOnly |
ReadWrite |

data OpenFileFlags

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

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

openFd

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

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 ()

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!

fdRead

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

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

fdReadBuf

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.

fdWriteBuf

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

May throw an exception if this is an invalid descriptor.

## File options

data FdOption

Constructors

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

queryFdOption :: Fd -> FdOption -> IO Bool

May throw an exception if this is an invalid descriptor.

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

May throw an exception if this is an invalid descriptor.

## Locking

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

data LockRequest

Constructors

ReadLock |
WriteLock |
Unlock |

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

May throw an exception if this is an invalid descriptor.

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

May throw an exception if this is an invalid descriptor.

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

May throw an exception if this is an invalid descriptor.

## Pipes

createPipe :: IO (Fd, Fd)

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

May throw an exception if this is an invalid descriptor.

dupTo :: Fd -> Fd -> IO Fd

May throw an exception if this is an invalid descriptor.

## Converting file descriptors to/from Handles

handleToFd :: Handle -> IO Fd

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

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.