-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Unix/Posix-specific functions for ByteStrings.
--   
--   Unix/Posix-specific functions for ByteStrings.
--   
--   Provides <tt>ByteString</tt> file-descriptor based I/O API, designed
--   loosely after the <tt>String</tt> file-descriptor based I/O API in
--   <a>System.Posix.IO</a>. The functions here wrap standard C
--   implementations of the functions specified by the ISO/IEC 9945-1:1990
--   (``POSIX.1'') and X/Open Portability Guide Issue 4, Version 2
--   (``XPG4.2'') specifications.
--   
--   Note that this package doesn't require the <tt>unix</tt> package as a
--   dependency. But you'll need it in order to get your hands on an
--   <tt>Fd</tt>, so we're not offering a complete replacement.
@package unix-bytestring
@version 0.3.5.4


-- | Imports the C <tt>struct iovec</tt> type and provides conversion
--   between <a>CIovec</a>s and strict <a>ByteString</a>s.
module System.Posix.Types.Iovec

-- | Haskell type representing the C <tt>struct iovec</tt> type. This is
--   exactly like <tt><a>CStringLen</a></tt> except there's actually struct
--   definition on the C side.
data CIovec
CIovec :: {-# UNPACK #-} !(Ptr Word8) -> {-# UNPACK #-} !CSize -> CIovec
iov_base :: CIovec -> {-# UNPACK #-} !(Ptr Word8)
iov_len :: CIovec -> {-# UNPACK #-} !CSize

-- | <i>O(1) construction</i> Convert a <tt>ByteString</tt> into an
--   <tt>CIovec</tt>.
--   
--   This function is <i>unsafe</i> in two ways:
--   
--   <ul>
--   <li>After calling this function the <tt>CIovec</tt> shares the
--   underlying byte buffer with the original <tt>ByteString</tt>. Thus,
--   modifying the <tt>CIovec</tt> either in C or using poke will cause the
--   contents of the <tt>ByteString</tt> to change, breaking referential
--   transparency. Other <tt>ByteStrings</tt> created by sharing (such as
--   those produced via <a>take</a> or <a>drop</a>) will also reflect these
--   changes.</li>
--   <li>Also, even though the <tt>CIovec</tt> shares the underlying byte
--   buffer, it does so in a way that will not keep the original
--   <tt>ByteString</tt> alive with respect to garbage collection. Thus,
--   the byte buffer could be collected out from under the <tt>CIovec</tt>.
--   To prevent this, you must use <a>touchByteString</a> after the last
--   point where the <tt>CIovec</tt> is needed.</li>
--   </ul>
unsafeByteString2CIovec :: ByteString -> CIovec

-- | Keep the <tt>ByteString</tt> alive. See
--   <a>unsafeByteString2CIovec</a>.
touchByteString :: ByteString -> IO ()

-- | <i>O(1) construction</i> Use a <tt>ByteString</tt> with a function
--   requiring a <tt>CIovec</tt>.
--   
--   This function does zero copying, and merely unwraps a
--   <tt>ByteString</tt> to appear as an <tt>CIovec</tt>. It is
--   <i>unsafe</i> in the same way as <a>unsafeByteString2CIovec</a>.
unsafeUseAsCIovec :: ByteString -> (CIovec -> IO a) -> IO a

-- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function
--   requiring a <tt>CIovec</tt>.
--   
--   As with <a>useAsCString</a> and <a>useAsCStringLen</a>, this function
--   makes a copy of the original <tt>ByteString</tt> via
--   <tt>memcpy(3)</tt>. The copy will be freed automatically. See
--   <a>unsafeUseAsCIovec</a> for a zero-copying version.
useAsCIovec :: ByteString -> (CIovec -> IO a) -> IO a
instance Storable CIovec


-- | Provides a variant of the <a>Foreign.C.Error</a> API which returns
--   errors explicitly, instead of throwing exceptions.
--   
--   <i>Since: 0.3.5</i>
module Foreign.C.Error.Safe

-- | A variant of <a>throwErrnoIf</a> which returns <tt>Either</tt> instead
--   of throwing an errno error.
eitherErrnoIf :: (a -> Bool) -> IO a -> IO (Either Errno a)

-- | A variant of <a>throwErrnoIfRetry</a> which returns <tt>Either</tt>
--   instead of throwing an errno error.
eitherErrnoIfRetry :: (a -> Bool) -> IO a -> IO (Either Errno a)

-- | A variant of <a>throwErrnoIfRetryMayBlock</a> which returns
--   <tt>Either</tt> instead of throwing an errno error.
eitherErrnoIfRetryMayBlock :: (a -> Bool) -> IO a -> IO b -> IO (Either Errno a)
eitherErrnoIfMinus1 :: (Eq a, Num a) => IO a -> IO (Either Errno a)
eitherErrnoIfMinus1Retry :: (Eq a, Num a) => IO a -> IO (Either Errno a)
eitherErrnoIfMinus1RetryMayBlock :: (Eq a, Num a) => IO a -> IO b -> IO (Either Errno a)
eitherErrnoIfNull :: IO (Ptr a) -> IO (Either Errno (Ptr a))
eitherErrnoIfNullRetry :: IO (Ptr a) -> IO (Either Errno (Ptr a))
eitherErrnoIfNullRetryMayBlock :: IO (Ptr a) -> IO b -> IO (Either Errno (Ptr a))


-- | Provides a strict-<a>ByteString</a> file-descriptor based I/O API,
--   designed loosely after the <tt>String</tt> file-descriptor based I/O
--   API in <a>System.Posix.IO</a>. The functions here wrap standard C
--   implementations of the functions specified by the ISO/IEC 9945-1:1990
--   (``POSIX.1'') and X/Open Portability Guide Issue 4, Version 2
--   (``XPG4.2'') specifications.
module System.Posix.IO.ByteString

-- | Read data from an <a>Fd</a> and convert it to a <a>ByteString</a>.
--   Throws an exception if this is an invalid descriptor, or EOF has been
--   reached. This is essentially equivalent to <a>fdReadBuf</a>; the
--   differences are that we allocate a byte buffer for the
--   <tt>ByteString</tt>, and that we detect EOF and throw an
--   <a>IOError</a>.
fdRead :: Fd -> ByteCount -> IO ByteString

-- | Read data from an <a>Fd</a> into memory. This is exactly equivalent to
--   the POSIX.1 <tt>read(2)</tt> system call, except that we return 0
--   bytes read if the <tt>ByteCount</tt> argument is less than or equal to
--   zero (instead of throwing an errno exception). <i>N.B.</i>, this
--   behavior is different from the version in <tt>unix-2.4.2.0</tt> which
--   only checks for equality to zero. If there are any errors, then they
--   are thrown as <a>IOError</a> exceptions.
--   
--   <i>Since: 0.3.0</i>
fdReadBuf :: Fd -> Ptr Word8 -> ByteCount -> IO ByteCount

-- | Read data from an <a>Fd</a> into memory. This is a variation of
--   <a>fdReadBuf</a> which returns errors with an <a>Either</a> instead of
--   throwing exceptions.
--   
--   <i>Since: 0.3.3</i>
tryFdReadBuf :: Fd -> Ptr Word8 -> ByteCount -> IO (Either Errno ByteCount)

-- | Read data from an <a>Fd</a> and convert it to a <a>ByteString</a>.
--   Throws an exception if this is an invalid descriptor, or EOF has been
--   reached.
--   
--   This version takes a kind of stateful predicate for whether and how
--   long to keep retrying. Assume the function is called as <tt>fdReads f
--   z0 fd n0</tt>. We will attempt to read <tt>n0</tt> bytes from
--   <tt>fd</tt>. If we fall short, then we will call <tt>f len z</tt>
--   where <tt>len</tt> is the total number of bytes read so far and
--   <tt>z</tt> is the current state (initially <tt>z0</tt>). If it returns
--   <tt>Nothing</tt> then we will give up and return the current buffer;
--   otherwise we will retry with the new state, continuing from where we
--   left off.
--   
--   For example, to define a function that tries up to <tt>n</tt> times,
--   we can use:
--   
--   <pre>
--   fdReadUptoNTimes :: Int -&gt; Fd -&gt; ByteCount -&gt; IO ByteString
--   fdReadUptoNTimes n0 = fdReads retry n0
--       where
--       retry _ 0 = Nothing
--       retry _ n = Just $! n-1
--   </pre>
--   
--   The benefit of doing this instead of the naive approach of calling
--   <a>fdRead</a> repeatedly is that we only need to allocate one byte
--   buffer, and trim it once at the end--- whereas the naive approach
--   would allocate a buffer, trim it to the number of bytes read, and then
--   concatenate with the previous one (another allocation, plus copying
--   everything over) for each time around the loop.
--   
--   <i>Since: 0.2.1</i>
fdReads :: (ByteCount -> a -> Maybe a) -> a -> Fd -> ByteCount -> IO ByteString

-- | Read data from an <a>Fd</a> and scatter it into memory. This is
--   exactly equivalent to the XPG4.2 <tt>readv(2)</tt> system call, except
--   that we return 0 bytes read if the <tt>Int</tt> argument is less than
--   or equal to zero (instead of throwing an <a>eINVAL</a> exception). If
--   there are any errors, then they are thrown as <a>IOError</a>
--   exceptions.
--   
--   TODO: better documentation.
--   
--   <i>Since: 0.3.0</i>
fdReadvBuf :: Fd -> Ptr CIovec -> Int -> IO ByteCount

-- | Read data from an <a>Fd</a> and scatter it into memory. This is a
--   variation of <a>fdReadvBuf</a> which returns errors with an
--   <a>Either</a> instead of throwing exceptions.
--   
--   <i>Since: 0.3.3</i>
tryFdReadvBuf :: Fd -> Ptr CIovec -> Int -> IO (Either Errno ByteCount)

-- | Read data from a specified position in the <a>Fd</a> and convert it to
--   a <a>ByteString</a>, without altering the position stored in the
--   <tt>Fd</tt>. Throws an exception if this is an invalid descriptor, or
--   EOF has been reached. This is essentially equivalent to
--   <a>fdPreadBuf</a>; the differences are that we allocate a byte buffer
--   for the <tt>ByteString</tt>, and that we detect EOF and throw an
--   <a>IOError</a>.
--   
--   <i>Since: 0.3.0</i>
fdPread :: Fd -> ByteCount -> FileOffset -> IO ByteString

-- | Read data from a specified position in the <a>Fd</a> into memory,
--   without altering the position stored in the <tt>Fd</tt>. This is
--   exactly equivalent to the XPG4.2 <tt>pread(2)</tt> system call, except
--   that we return 0 bytes read if the <tt>Int</tt> argument is less than
--   or equal to zero (instead of throwing an errno exception). If there
--   are any errors, then they are thrown as <a>IOError</a> exceptions.
--   
--   <i>Since: 0.3.0</i>
fdPreadBuf :: Fd -> Ptr Word8 -> ByteCount -> FileOffset -> IO ByteCount

-- | Read data from a specified position in the <a>Fd</a> into memory,
--   without altering the position stored in the <tt>Fd</tt>. This is a
--   variation of <a>fdPreadBuf</a> which returns errors with an
--   <a>Either</a> instead of throwing exceptions.
--   
--   <i>Since: 0.3.3</i>
tryFdPreadBuf :: Fd -> Ptr Word8 -> ByteCount -> FileOffset -> IO (Either Errno ByteCount)

-- | Read data from a specified position in the <a>Fd</a> and convert it to
--   a <a>ByteString</a>, without altering the position stored in the
--   <tt>Fd</tt>. Throws an exception if this is an invalid descriptor, or
--   EOF has been reached. This is a <a>fdPreadBuf</a> based version of
--   <a>fdReads</a>; see those functions for more details.
--   
--   <i>Since: 0.3.1</i>
fdPreads :: (ByteCount -> a -> Maybe a) -> a -> Fd -> ByteCount -> FileOffset -> IO ByteString

-- | Write a <a>ByteString</a> to an <a>Fd</a>. The return value is the
--   total number of bytes actually written. This is exactly equivalent to
--   <a>fdWriteBuf</a>; we just convert the <tt>ByteString</tt> into its
--   underlying <tt>Ptr Word8</tt> and <tt>ByteCount</tt> components for
--   passing to <a>fdWriteBuf</a>.
fdWrite :: Fd -> ByteString -> IO ByteCount

-- | Write data from memory to an <a>Fd</a>. This is exactly equivalent to
--   the POSIX.1 <tt>write(2)</tt> system call, except that we return 0
--   bytes written if the <tt>ByteCount</tt> argument is less than or equal
--   to zero (instead of throwing an errno exception). <i>N.B.</i>, this
--   behavior is different from the version in <tt>unix-2.4.2.0</tt> which
--   doesn't check the byte count. If there are any errors, then they are
--   thrown as <a>IOError</a> exceptions.
--   
--   <i>Since: 0.3.0</i>
fdWriteBuf :: Fd -> Ptr Word8 -> ByteCount -> IO ByteCount

-- | Write data from memory to an <a>Fd</a>. This is a variation of
--   <a>fdWriteBuf</a> which returns errors with an <a>Either</a> instead
--   of throwing exceptions.
--   
--   <i>Since: 0.3.3</i>
tryFdWriteBuf :: Fd -> Ptr Word8 -> ByteCount -> IO (Either Errno ByteCount)

-- | Write a sequence of <a>ByteString</a>s to an <a>Fd</a>. The return
--   value is a triple of: the total number of bytes written, the number of
--   bytes written from the first of the remaining strings, and the
--   remaining (unwritten) strings. We return this triple instead of a pair
--   adjusting the head of the remaining strings (i.e., removing the bytes
--   already written) in case there is some semantic significance to the
--   way the input is split into chunks.
--   
--   This version consumes the list lazily and will call <a>fdWrite</a>
--   once for each <tt>ByteString</tt>, thus making <i>O(n)</i> system
--   calls. This laziness allows the early parts of the list to be garbage
--   collected and prevents needing to hold the whole list of
--   <tt>ByteString</tt>s in memory at once. Compare against
--   <a>fdWritev</a>.
fdWrites :: Fd -> [ByteString] -> IO (ByteCount, ByteCount, [ByteString])

-- | Write a sequence of <a>ByteString</a>s to an <a>Fd</a>. The return
--   value is the total number of bytes written. Unfortunately the
--   <tt>writev(2)</tt> system call does not provide enough information to
--   return the triple that <a>fdWrites</a> does.
--   
--   This version will force the spine of the list, converting each
--   <tt>ByteString</tt> into an <tt>iovec</tt> (see <a>CIovec</a>), and
--   then call <a>fdWritevBuf</a>. This means we only make one system call,
--   which reduces the overhead of performing context switches. But it also
--   means that we must store the whole list of <tt>ByteString</tt>s in
--   memory at once, and that we must perform some allocation and
--   conversion. Compare against <a>fdWrites</a>.
fdWritev :: Fd -> [ByteString] -> IO ByteCount

-- | Write data from memory to an <a>Fd</a>. This is exactly equivalent to
--   the XPG4.2 <tt>writev(2)</tt> system call, except that we return 0
--   bytes written if the <tt>Int</tt> argument is less than or equal to
--   zero (instead of throwing an <a>eINVAL</a> exception). If there are
--   any errors, then they are thrown as <a>IOError</a> exceptions.
--   
--   TODO: better documentation.
--   
--   <i>Since: 0.3.0</i>
fdWritevBuf :: Fd -> Ptr CIovec -> Int -> IO ByteCount

-- | Write data from memory to an <a>Fd</a>. This is a variation of
--   <a>fdWritevBuf</a> which returns errors with an <a>Either</a> instead
--   of throwing exceptions.
--   
--   <i>Since: 0.3.3</i>
tryFdWritevBuf :: Fd -> Ptr CIovec -> Int -> IO (Either Errno ByteCount)

-- | Write data from memory to a specified position in the <a>Fd</a>, but
--   without altering the position stored in the <tt>Fd</tt>. This is
--   exactly equivalent to <a>fdPwriteBuf</a>; we just convert the
--   <tt>ByteString</tt> into its underlying <tt>Ptr Word8</tt> and
--   <tt>ByteCount</tt> components for passing to <a>fdPwriteBuf</a>.
--   
--   <i>Since: 0.3.0</i>
fdPwrite :: Fd -> ByteString -> FileOffset -> IO ByteCount

-- | Write data from memory to a specified position in the <a>Fd</a>, but
--   without altering the position stored in the <tt>Fd</tt>. This is
--   exactly equivalent to the XPG4.2 <tt>pwrite(2)</tt> system call,
--   except that we return 0 bytes written if the <tt>ByteCount</tt>
--   argument is less than or equal to zero (instead of throwing an errno
--   exception). If there are any errors, then they are thrown as
--   <a>IOError</a> exceptions.
--   
--   <i>Since: 0.3.0</i>
fdPwriteBuf :: Fd -> Ptr Word8 -> ByteCount -> FileOffset -> IO ByteCount

-- | Write data from memory to a specified position in the <a>Fd</a>, but
--   without altering the position stored in the <tt>Fd</tt>. This is a
--   variation of <a>fdPwriteBuf</a> which returns errors with an
--   <a>Either</a> instead of throwing exceptions.
--   
--   <i>Since: 0.3.3</i>
tryFdPwriteBuf :: Fd -> Ptr Word8 -> ByteCount -> FileOffset -> IO (Either Errno ByteCount)

-- | Repositions the offset of the file descriptor according to the offset
--   and the seeking mode. This is exactly equivalent to the POSIX.1
--   <tt>lseek(2)</tt> system call. If there are any errors, then they are
--   thrown as <a>IOError</a> exceptions.
--   
--   This is the same as <a>fdSeek</a> in <tt>unix-2.4.2.0</tt>, but
--   provided here for consistency.
--   
--   <i>Since: 0.3.5</i>
fdSeek :: Fd -> SeekMode -> FileOffset -> IO FileOffset

-- | Repositions the offset of the file descriptor according to the offset
--   and the seeking mode. This is a variation of <a>fdSeek</a> which
--   returns errors with an <tt>Either</tt> instead of throwing exceptions.
--   
--   <i>Since: 0.3.5</i>
tryFdSeek :: Fd -> SeekMode -> FileOffset -> IO (Either Errno FileOffset)


-- | Provides a lazy-<a>ByteString</a> file-descriptor based I/O API,
--   designed loosely after the <tt>String</tt> file-descriptor based I/O
--   API in <a>System.Posix.IO</a>. The functions here wrap standard C
--   implementations of the functions specified by the ISO/IEC 9945-1:1990
--   (``POSIX.1'') and X/Open Portability Guide Issue 4, Version 2
--   (``XPG4.2'') specifications.
--   
--   These functions are provided mainly as a convenience to avoid
--   boilerplate code converting between lazy <a>ByteString</a> and strict
--   <tt>[<a>ByteString</a>]</tt>. It may be depricated in the future.
module System.Posix.IO.ByteString.Lazy

-- | Read data from an <a>Fd</a> and convert it to a <a>ByteString</a>.
--   Throws an exception if this is an invalid descriptor, or EOF has been
--   reached. This is a thin wrapper around <a>fdRead</a>.
fdRead :: Fd -> ByteCount -> IO ByteString

-- | Read data from a specified position in the <a>Fd</a> and convert it to
--   a <a>ByteString</a>, without altering the position stored in the
--   <tt>Fd</tt>. Throws an exception if this is an invalid descriptor, or
--   EOF has been reached. This is a thin wrapper around <a>fdPread</a>.
--   
--   <i>Since: 0.3.1</i>
fdPread :: Fd -> ByteCount -> FileOffset -> IO ByteString

-- | Write a <a>ByteString</a> to an <a>Fd</a>. This function makes one
--   <tt>write(2)</tt> system call per chunk, as per <a>fdWrites</a>.
fdWrites :: Fd -> ByteString -> IO (ByteCount, ByteString)

-- | Write a <a>ByteString</a> to an <a>Fd</a>. This function makes a
--   single <tt>writev(2)</tt> system call, as per <a>fdWritev</a>.
fdWritev :: Fd -> ByteString -> IO ByteCount
