| Haskell Hierarchical Libraries (unix package) | Contents | Index

System.Posix.IO

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

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 `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
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 |

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

:: 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

:: Fd |
-> ByteCount | How many bytes to read
-> IO (String, ByteCount) | The bytes read, how many bytes were read.
May throw an exception if this is an invalid descriptor.

fdWrite :: Fd -> String -> IO ByteCount
May throw an exception if this is an invalid descriptor.
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.
Produced by Haddock version 0.7