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

-- | A toy module to temporarily redirect a program's stdout.
--   
--   Due to the design of POSIX, it is possible to temporarily overload the
--   file descriptors corresponding to stdout and stderr to point to an
--   arbitrary pipe. It is, however, tricky to get right. This module gets
--   it right, as far as such a terrible hack can be made right. It can be
--   used to make misbehaving third-party C libraries stop spewing to
--   standard output. Warning: the module author has concluded that due to
--   lack of portability, this module should not be used in any serious
--   sytem. But, for those who like living dangerously...
@package system-posix-redirect
@version 1.1.0.1

-- | Misbehaved third-party libraries (usually not written in Haskell) may
--   print error messages directly to stdout or stderr when we would
--   actually like to capture them and propagate them as a normal
--   exception. In such cases, it would be useful to temporarily override
--   those file descriptors to point to a pipe that we control.
--   
--   This module is not portable and not thread safe. However, it can
--   safely manage arbitrarily large amounts of data, as it spins off
--   another thread to read from the pipe created; therefore, you must use
--   -threaded to compile a program with this. If you are making a foreign
--   call, you must ensure that the foreign call is marked safe or there is
--   a possibility of deadlock.
--   
--   While this module is an interesting novelty, it is the module author's
--   opinion that it is not a sustainable method for making C libraries
--   behave properly, primarily due to its unportability (this trick does
--   not appear to be possible on Windows). Use at your own risk.
module System.Posix.Redirect

-- | redirectStdout f redirects standard output during the
--   execution of f into a pipe passed as the first argument to
--   f.
redirectStdout :: IO a -> IO (ByteString, a)

-- | redirectStderr f redirects standard error during the
--   execution of f into a pipe passed as the first argument to
--   f.
redirectStderr :: IO a -> IO (ByteString, a)

-- | redirectWriteHandle oldFd oldHandle oldCHandle f
--   executes the computation f, passing as an argument a handle
--   which is the read end of a pipe that fd now points to. This
--   function appropriately flushes the Haskell oldHandle and the
--   C oldCHandle before and after f's execution.
redirectWriteHandle :: Fd -> Handle -> Ptr FILE -> IO a -> IO (ByteString, a)

-- | unsafeRedirectFd fd f executes the computation
--   f, passing as an argument a handle which is the read end of a
--   pipe that fd now points to. When the computation is done, the
--   original file descriptor is restored. Use with care: if there are any
--   file handles with this descriptor that have unflushed buffers, they
--   will not flush to the old file descriptor, but the new file
--   descriptor.
unsafeRedirectWriteFd :: Fd -> IO a -> IO (ByteString, a)
