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 | Trustworthy |
Language | Haskell2010 |
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
- data OpenFileFlags = OpenFileFlags {}
- defaultFileFlags :: OpenFileFlags
- openFd :: RawFilePath -> OpenMode -> OpenFileFlags -> IO Fd
- openFdAt :: Maybe Fd -> RawFilePath -> OpenMode -> OpenFileFlags -> IO Fd
- createFile :: RawFilePath -> FileMode -> IO Fd
- createFileAt :: Maybe Fd -> RawFilePath -> FileMode -> IO Fd
- closeFd :: Fd -> IO ()
- fdRead :: Fd -> ByteCount -> IO ByteString
- fdWrite :: Fd -> ByteString -> IO ByteCount
- fdReadBuf :: Fd -> Ptr Word8 -> ByteCount -> IO ByteCount
- fdWriteBuf :: Fd -> Ptr Word8 -> ByteCount -> IO ByteCount
- fdSeek :: Fd -> SeekMode -> FileOffset -> IO FileOffset
- data FdOption
- queryFdOption :: Fd -> FdOption -> IO Bool
- setFdOption :: Fd -> FdOption -> Bool -> IO ()
- type FileLock = (LockRequest, SeekMode, FileOffset, FileOffset)
- data LockRequest
- 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
Opening and closing files
data OpenFileFlags Source #
Correspond to some of the int flags from C's fcntl.h.
OpenFileFlags | |
|
Instances
Read OpenFileFlags Source # | |
Defined in System.Posix.IO.Common readsPrec :: Int -> ReadS OpenFileFlags # readList :: ReadS [OpenFileFlags] # | |
Show OpenFileFlags Source # | |
Defined in System.Posix.IO.Common showsPrec :: Int -> OpenFileFlags -> ShowS # show :: OpenFileFlags -> String # showList :: [OpenFileFlags] -> ShowS # | |
Eq OpenFileFlags Source # | |
Defined in System.Posix.IO.Common (==) :: OpenFileFlags -> OpenFileFlags -> Bool # (/=) :: OpenFileFlags -> OpenFileFlags -> Bool # | |
Ord OpenFileFlags Source # | |
Defined in System.Posix.IO.Common 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 Source #
Default values for the OpenFileFlags
type.
Each field of OpenFileFlags
is either False
or Nothing
respectively.
openFd :: RawFilePath -> OpenMode -> OpenFileFlags -> IO Fd Source #
:: Maybe Fd | Optional directory file descriptor |
-> RawFilePath | 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 :: RawFilePath -> FileMode -> IO Fd Source #
:: Maybe Fd | Optional directory file descriptor |
-> RawFilePath | 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 () 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!
:: 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 Source #
Write a ByteString
to an Fd
.
:: 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.
:: 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 Source #
May throw an exception if this is an invalid descriptor.
File options
AppendOnWrite | O_APPEND |
CloseOnExec | FD_CLOEXEC |
NonBlockingRead | O_NONBLOCK |
SynchronousWrites | O_SYNC |
queryFdOption :: Fd -> FdOption -> IO Bool Source #
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
type FileLock = (LockRequest, SeekMode, FileOffset, FileOffset) Source #
getLock :: Fd -> FileLock -> IO (Maybe (ProcessID, FileLock)) 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
Converting file descriptors to/from Handles
handleToFd :: Handle -> IO Fd Source #
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.