System.Posix.IO.PosixString

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.

Input / Output

Standard file descriptors

stdInput :: Fd

stdOutput :: Fd

stdError :: Fd

Opening and closing files

data OpenMode

Constructors

ReadOnly

WriteOnly

ReadWrite

Instances

Read OpenMode

Defined in System.Posix.IO.Common

Methods

readsPrec :: Int -> ReadS OpenMode

readList :: ReadS [OpenMode]

readPrec :: ReadPrec OpenMode

readListPrec :: ReadPrec [OpenMode]

Show OpenMode

Defined in System.Posix.IO.Common

Methods

showsPrec :: Int -> OpenMode -> ShowS

show :: OpenMode -> String

showList :: [OpenMode] -> ShowS

Eq OpenMode

Defined in System.Posix.IO.Common

Methods

(==) :: OpenMode -> OpenMode -> Bool

(/=) :: OpenMode -> OpenMode -> Bool

Ord OpenMode

Defined in System.Posix.IO.Common

Methods

compare :: OpenMode -> OpenMode -> Ordering

(<) :: OpenMode -> OpenMode -> Bool

(<=) :: OpenMode -> OpenMode -> Bool

(>) :: OpenMode -> OpenMode -> Bool

(>=) :: OpenMode -> OpenMode -> Bool

max :: OpenMode -> OpenMode -> OpenMode

min :: OpenMode -> OpenMode -> OpenMode

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, result is undefined if O_CREAT is False

  NOTE: Result is undefined if creat is Nothing.

• noctty :: Bool

  O_NOCTTY

• nonBlock :: Bool

  O_NONBLOCK

• trunc :: Bool

  O_TRUNC

• nofollow :: Bool

  O_NOFOLLOW

  Since: 2.8.0.0

• creat :: Maybe FileMode

  O_CREAT

  Since: 2.8.0.0

• cloexec :: Bool

  O_CLOEXEC

  Since: 2.8.0.0

• directory :: Bool

  O_DIRECTORY

  Since: 2.8.0.0

• sync :: Bool

  O_SYNC

  Since: 2.8.0.0

Instances

Read OpenFileFlags

Defined in System.Posix.IO.Common

Methods

readsPrec :: Int -> ReadS OpenFileFlags

readList :: ReadS [OpenFileFlags]

readPrec :: ReadPrec OpenFileFlags

readListPrec :: ReadPrec [OpenFileFlags]

Show OpenFileFlags

Defined in System.Posix.IO.Common

Methods

showsPrec :: Int -> OpenFileFlags -> ShowS

show :: OpenFileFlags -> String

showList :: [OpenFileFlags] -> ShowS

Eq OpenFileFlags

Defined in System.Posix.IO.Common

Methods

(==) :: OpenFileFlags -> OpenFileFlags -> Bool

(/=) :: OpenFileFlags -> OpenFileFlags -> Bool

Ord OpenFileFlags

Defined in System.Posix.IO.Common

Methods

compare :: OpenFileFlags -> OpenFileFlags -> Ordering

(<) :: OpenFileFlags -> OpenFileFlags -> Bool

(<=) :: OpenFileFlags -> OpenFileFlags -> Bool

(>) :: OpenFileFlags -> OpenFileFlags -> Bool

(>=) :: OpenFileFlags -> OpenFileFlags -> Bool

max :: OpenFileFlags -> OpenFileFlags -> OpenFileFlags

min :: OpenFileFlags -> OpenFileFlags -> OpenFileFlags

defaultFileFlags :: OpenFileFlags

Default values for the OpenFileFlags type.

Each field of OpenFileFlags is either False or Nothing respectively.

openFd :: PosixPath -> OpenMode -> OpenFileFlags -> IO Fd

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

openFdAt

Arguments

:: Maybe Fd

Optional directory file descriptor

-> PosixPath

Pathname to open

-> OpenMode

Read-only, read-write or write-only

-> OpenFileFlags

Append, exclusive, truncate, etc.

-> IO Fd

Open a file relative to an optional directory file descriptor.

Directory file descriptors can be used to avoid some race conditions when navigating changing directory trees, or to retain access to a portion of the directory tree that would otherwise become inaccessible after dropping privileges.

createFile :: PosixPath -> 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.

createFileAt

Arguments

:: Maybe Fd

Optional directory file descriptor

-> PosixPath

Pathname to create

-> FileMode

File permission bits (before umask)

-> IO Fd

Create and open a file for write-only, with default flags, relative an optional directory file-descriptor.

Directory file descriptors can be used to avoid some race conditions when navigating changing directory trees, or to retain access to a portion of the directory tree that would otherwise become inaccessible after dropping privileges.

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 ByteString

The bytes read

Read data from an Fd and return it as a ByteString. Throws an exception if this is an invalid descriptor, or EOF has been reached.

fdWrite :: Fd -> ByteString -> IO ByteCount

Write a ByteString to an Fd.

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), without closing the underlying Fd.

Warning: This means you take over ownership of the underlying Fd. hClose on the Handle will no longer have any effect. This will break common patterns to avoid file descriptor leaks, such as using hClose in the cleanup action of Control.Exception.bracket, making it a silent no-op. Be sure to close the returned Fd yourself to not leak it.

fdToHandle :: Fd -> IO Handle

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