unix-2.5.1.0: POSIX functionality

Portabilitynon-portable (requires POSIX)
Stabilityprovisional
Maintainerlibraries@haskell.org
Safe HaskellTrustworthy

System.Posix.IO

Contents

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

Input / Output

Standard file descriptors

Opening and closing files

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

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 Files for information on how to use the FileMode type.

createFile :: FilePath -> FileMode -> IO FdSource

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 ()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 using the locale encoding. Throws an exception if this is an invalid descriptor, or EOF has been reached.

fdWrite :: Fd -> String -> IO ByteCountSource

Write a String to an Fd using the locale encoding.

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 FileOffsetSource

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 BoolSource

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

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 FdSource

May throw an exception if this is an invalid descriptor.

dupTo :: Fd -> Fd -> IO FdSource

May throw an exception if this is an invalid descriptor.

Converting file descriptors to/from Handles

handleToFd :: Handle -> IO FdSource

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 HandleSource

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.