unix-2.7.2.2: POSIX functionality

Copyright | (c) The University of Glasgow 2002
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | provisional
Portability | non-portable (requires POSIX)
Safe Haskell | Safe
Language | Haskell2010

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 `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 `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` using the locale encoding. 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` using the locale encoding.

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