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


-- | A crude interface between Haskell and Unix-like operating systems
--   
--   A collection of useful and mildly useful functions that you might
--   expect to find in System.* which a heavy bias towards Unix-type
--   operating systems.
@package Unixutils
@version 1.46

module System.Unix.Files

-- | calls <a>createSymbolicLink</a> but will remove the target and retry
--   if <a>createSymbolicLink</a> raises EEXIST.
forceSymbolicLink :: FilePath -> FilePath -> IO ()


-- | Construct an ADT representing block and character devices (but mostly
--   block devices) by interpreting the contents of the Linux sysfs
--   filesystem.
module System.Unix.SpecialDevice
data SpecialDevice

-- | FIXME: We should really get this value from the mount table.
sysMountPoint :: FilePath

-- | Return the device represented by a device node, such as /dev/sda2.
--   Returns Nothing if there is an exception trying to stat the node, or
--   if the node turns out not to be a special device.
ofNode :: FilePath -> IO (Maybe SpecialDevice)
ofNodeStatus :: FileStatus -> Maybe SpecialDevice
ofPath :: FilePath -> IO (Maybe SpecialDevice)
rootPart :: IO (Maybe SpecialDevice)
ofDevNo :: (DeviceID -> SpecialDevice) -> Int -> SpecialDevice
ofSysName :: String -> IO (Maybe SpecialDevice)
ofSysPath :: (DeviceID -> SpecialDevice) -> FilePath -> IO (Maybe SpecialDevice)
toDevno :: SpecialDevice -> DeviceID
ofMajorMinor :: (DeviceID -> SpecialDevice) -> Int -> Int -> SpecialDevice
node :: SpecialDevice -> IO (Maybe FilePath)
nodes :: SpecialDevice -> IO [FilePath]
sysName :: SpecialDevice -> IO (Maybe String)
splitPart :: String -> (String, Int)
sysDir :: SpecialDevice -> IO (Maybe FilePath)
diskOfPart :: SpecialDevice -> IO (Maybe SpecialDevice)
getAllDisks :: IO [SpecialDevice]
getAllPartitions :: IO [SpecialDevice]
getAllCdroms :: IO [SpecialDevice]
getAllRemovable :: IO [SpecialDevice]
instance Show SpecialDevice
instance Ord SpecialDevice
instance Eq SpecialDevice


-- | support for <i>etc</i>shadow
--   
--   TODO: This module is modelled after System.Posix.User but lacks many
--   of the #ifdefs. Those are probably important.
module System.Unix.Shadow

-- | Entry returned by <a>getSUserEntryForName</a>
--   
--   TODO: add other fields
data SUserEntry
SUserEntry :: String -> String -> SUserEntry

-- | Textual name of this user (pw_name)
sUserName :: SUserEntry -> String

-- | Password -- may be empty or fake if shadow is in use (pw_passwd)
sUserPassword :: SUserEntry -> String

-- | <tt>getSUserEntryForName name</tt> calls <tt>getspnam</tt> to obtain
--   the <tt>SUserEntry</tt> information associated with the user login
--   <tt>name</tt>.p
getSUserEntryForName :: String -> IO SUserEntry
instance Show SUserEntry
instance Read SUserEntry
instance Eq SUserEntry


-- | Run shell commands with various types of progress reporting.
--   
--   Author: David Fox
module System.Unix.OldProgress

-- | Create a task that sends its output to a handle and then can be
--   terminated using an IO operation that returns an exit status. Throws
--   an error if the command fails.
systemTask :: [Style] -> String -> IO TimeDiff
otherTask :: [Style] -> IO a -> IO a
data Style

-- | Message printed before the execution begins
Start :: String -> Style

-- | Message printed on successful termination
Finish :: String -> Style

-- | Message printed on failure
Error :: String -> Style

-- | Type of output to generate during execution
Output :: Output -> Style

-- | If true, echo the shell command before beginning
Echo :: Bool -> Style

-- | If true print the elapsed time on termination
Elapsed :: Bool -> Style

-- | Set the verbosity level. This value can be queried using the verbosity
--   function, but is not otherwise used by the -- functions in this
--   module.
Verbosity :: Int -> Style

-- | Set the indentation string for the generated output.
Indent :: String -> Style
readStyle :: String -> Maybe Style
data Output

-- | Print all the command's output with each line indented using (by
--   default) the string ' &gt; '.
Indented :: Output

-- | Print a dot for every 1024 characters the command outputs
Dots :: Output

-- | Print an ellipsis (...) when the command starts and then <a>done.</a>
--   when it finishes.
Done :: Output

-- | Print nothing.
Quiet :: Output
msg :: [Style] -> String -> IO ()
msgLn :: [Style] -> String -> IO ()
output :: [Style] -> Maybe Output
verbosity :: [Style] -> Int

-- | Add styles, replacing old ones if present
setStyles :: [Style] -> [Style] -> [Style]

-- | Singleton case of setStyles
setStyle :: Style -> [Style] -> [Style]

-- | Add styles only if not present
addStyles :: [Style] -> [Style] -> [Style]

-- | Singleton case of addStyles
addStyle :: Style -> [Style] -> [Style]

-- | Remove styles by class
removeStyle :: Style -> [Style] -> [Style]
stripDist :: FilePath -> FilePath
showElapsed :: String -> IO a -> IO a

-- | records the difference between two clock times in a user-readable way.
data TimeDiff :: *

-- | null time difference.
noTimeDiff :: TimeDiff

-- | The timeDiffToString function returns the empty string for the zero
--   time diff, this is not the behavior I need.
fixedTimeDiffToString :: TimeDiff -> [Char]
instance Eq Style
instance Show Style
instance Show Output


-- | The function splitFileName is taken from missingh, at the moment
--   missingh will not build under sid.
module System.Unix.FilePath

-- | Concatenate two paths, making sure there is exactly one path
--   separator.
--   
--   Use dropFileName
dirName :: FilePath -> FilePath

-- | Use takeFileName
baseName :: FilePath -> String

-- | resolve all references to <i>.</i>, <i>..</i>, extra slashes, and
--   symlinks
realpath :: FilePath -> IO FilePath
(<++>) :: FilePath -> FilePath -> FilePath

module System.Unix.Directory

-- | Traverse a directory and return a list of all the (path, fileStatus)
--   pairs.
find :: FilePath -> IO [(FilePath, FileStatus)]

-- | Recursively remove a directory contents on a single file system. The
--   adjective "Safely" refers to these features: 1. It will not follow
--   symlinks 2. If it finds a directory that seems to be a mount point, it
--   will attempt to unmount it up to five times. If it still seems to be a
--   mount point it gives up 3. It doesn't use <i>proc</i>mounts, which is
--   ambiguous or wrong when you are inside a chroot.
removeRecursiveSafely :: FilePath -> IO ()

-- | Like removeRecursiveSafely but doesn't remove any files, just unmounts
--   anything it finds mounted. Note that this can be much slower than
--   Mount.umountBelow, use that instead.
unmountRecursiveSafely :: FilePath -> IO ()

-- | Rename src to dst, and if dst already exists move it to dst~. If dst~
--   exists it is removed.
renameFileWithBackup :: FilePath -> FilePath -> IO ()

-- | temporarily change the working directory to |dir| while running
--   |action|
withWorkingDirectory :: FilePath -> IO a -> IO a

-- | create a temporary directory, run the action, remove the temporary
--   directory the first argument is a template for the temporary directory
--   name the directory will be created as a subdirectory of the directory
--   returned by getTemporaryDirectory the temporary directory will be
--   automatically removed afterwards. your working directory is not
--   altered
withTemporaryDirectory :: FilePath -> (FilePath -> IO a) -> IO a
mkdtemp :: FilePath -> IO FilePath


-- | support for crypt() and <i>etc</i>shadow
module System.Unix.Crypt

-- | calls crypt(3)
crypt :: String -> String -> IO String


-- | Functions to manage the verbosity of a console program by storing the
--   quietness level in the system environment, specifically in the
--   $QUIETNESS variable. This lets you avoid creating a StateT monad to
--   hold the quietness level. Note that you don't attach a verbosity level
--   to individual message commands, you control the quietness level for
--   entire regions of your program and messages only appear when quietness
--   is less than one.
module System.Unix.QIO
ePutStr :: MonadIO m => String -> m ()
ePutStrLn :: MonadIO m => String -> m ()
eMessage :: MonadIO m => String -> b -> m b
eMessageLn :: MonadIO m => String -> b -> m b

-- | Compute an initial value for $QUIETNESS by examining the $QUIETNESS
--   and $VERBOSITY variables and counting the -v and -q options on the
--   command line.
initialQuietness :: MonadIO m => m Int

-- | Get the current quietness level from the QUIETNESS environment
--   variable.
quietness :: MonadIO m => m Int

-- | Perform a task with the quietness level tansformed by f. Use
--   <tt>defaultQuietness &gt;&gt;= modQuietness . const</tt> to initialize
--   the -- verbosity for a program.
quieter :: MonadIO m => (Int -> Int) -> m a -> m a

-- | Dummy version of quieter, sometimes you want to strip out all the
--   quieter calls and see how things look, then restore them gradually.
--   Use this to help remember where they were.
quieter' :: MonadIO m => (Int -> Int) -> m a -> m a

-- | Peform a task only if quietness &lt; 1.
qDo :: MonadIO m => m () -> m ()

-- | If the current quietness level is less than one print a message.
--   Control the quietness level using <tt>quieter</tt>.
qPutStr :: MonadIO m => String -> m ()

-- | <tt>qPutStr</tt> with a terminating newline.
qPutStrLn :: MonadIO m => String -> m ()

-- | <tt>eMessage</tt> controlled by the quietness level.
qMessage :: MonadIO m => String -> a -> m a

-- | <tt>qMessage</tt> with a terminating newline.
qMessageLn :: MonadIO m => String -> a -> m a

-- | Print a message at quietness +1 and then do a task at quietness +3.
--   This is a pattern which gives the following behaviors: Normally there
--   is no output. With -v only the messages are printed. With -v -v the
--   messages and the shell commands are printed with dots to show
--   progress. With -v -v -v everything is printed.
q12 :: MonadIO m => String -> m a -> m a
q02 :: MonadIO m => String -> m a -> m a
v1 :: MonadIO m => m a -> m a
v2 :: MonadIO m => m a -> m a
v3 :: MonadIO m => m a -> m a

-- | For debugging
showQ :: MonadIO m => String -> m a -> m a


-- | functions for killing processes, running processes, etc
module System.Unix.Process

-- | This is the type returned by <a>runInteractiveProcess</a> et. al.
type Process = (Handle, Handle, Handle, ProcessHandle)

-- | The lazyCommand, lazyProcess and lazyRun functions each return a list
--   of <a>Output</a>. There will generally be one Result value at or near
--   the end of the list (if the list has an end.)
data Output
Stdout :: ByteString -> Output
Stderr :: ByteString -> Output
Result :: ExitCode -> Output

-- | Take the tuple like that returned by <a>runInteractiveProcess</a>,
--   create a process, send the list of inputs to its stdin and return the
--   lazy list of <a>Output</a> objects.
lazyRun :: MonadIO m => ByteString -> Process -> m Outputs

-- | Create a process with <a>runInteractiveCommand</a> and run it with
--   <a>lazyRun</a>.
lazyCommand :: MonadIO m => String -> ByteString -> m Outputs

-- | Create a process with <a>runInteractiveProcess</a> and run it with
--   <a>lazyRun</a>.
lazyProcess :: MonadIO m => FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> ByteString -> m Outputs

-- | Filter everything except stdout from the output list.
stdoutOnly :: Outputs -> ByteString

-- | Filter everything except stderr from the output list.
stderrOnly :: Outputs -> ByteString

-- | Filter the exit codes output list and merge the two output streams in
--   the order they appear.
outputOnly :: Outputs -> ByteString
checkResult :: (Int -> a) -> a -> Outputs -> a
discardStdout :: Outputs -> Outputs
discardStderr :: Outputs -> Outputs
discardOutput :: Outputs -> Outputs

-- | Turn all the Stdout text into Stderr, preserving the order.
mergeToStderr :: Outputs -> Outputs

-- | Turn all the Stderr text into Stdout, preserving the order.
mergeToStdout :: Outputs -> Outputs

-- | Split out and concatenate Stdout
collectStdout :: Outputs -> (ByteString, Outputs)

-- | Split out and concatenate Stderr
collectStderr :: Outputs -> (ByteString, Outputs)

-- | Split out and concatenate both Stdout and Stderr, leaving only the
--   exit code.
collectOutput :: Outputs -> (ByteString, ByteString, ExitCode)

-- | Collect all output, unpack and concatenate.
collectOutputUnpacked :: Outputs -> (String, String, ExitCode)

-- | Partition the exit code from the outputs.
collectResult :: Outputs -> (ExitCode, Outputs)

-- | Defines the exit codes that a program can return.
data ExitCode :: *

-- | indicates successful termination;
ExitSuccess :: ExitCode

-- | indicates program failure with an exit code. The exact interpretation
--   of the code is operating-system dependent. In particular, some values
--   may be prohibited (e.g. 0 on a POSIX-compliant system).
ExitFailure :: Int -> ExitCode

-- | Filter everything except the exit code from the output list. See
--   discussion in <a>lazyRun</a> of why we are confident that the list
--   will contain exactly one <a>Result</a>. An opaque type to hold the
--   <a>Output</a> list would lend additional safety here.
exitCodeOnly :: Outputs -> ExitCode

-- | This belongs in Data.ByteString. See ticket 1070,
--   <a>http://hackage.haskell.org/trac/ghc/ticket/1070</a>.
hPutNonBlocking :: Handle -> ByteString -> IO Int64

-- | Kill the processes whose working directory is in or under the given
--   directory.
killByCwd :: FilePath -> IO [(String, Maybe String)]
instance Show Output


-- | Support for changing the output of a lazyCommand in several ways:
--   
--   <ul>
--   <li>Output a dot for every 128 characters of the original output</li>
--   <li>Increase the quietness level before running the command</li>
--   <li>Output only if (and when) the command fails</li>
--   <li>Throw an exception if the command fails</li>
--   <li>No output</li>
--   </ul>
module System.Unix.Progress

-- | The flags that control what type of output will be sent to stdout and
--   stderr. Also, the ExceptionOnFail flag controls whether an exception
--   will be thrown if the <tt>ExitCode</tt> is not <tt>ExitSuccess</tt>.
data ProgressFlag
Echo :: ProgressFlag
Dots :: ProgressFlag
All :: ProgressFlag
Errors :: ProgressFlag
Result :: ProgressFlag

-- | If Echo is present this has no effect
EchoOnFail :: ProgressFlag

-- | If All is present this has no effect
AllOnFail :: ProgressFlag
ErrorsOnFail :: ProgressFlag
ResultOnFail :: ProgressFlag
ExceptionOnFail :: ProgressFlag

-- | The <tt>P</tt> versions are the most general cases, here you can
--   specify a function that turns the quietness level into any set of
--   progress flags you like.
lazyCommandP :: MonadIO m => String -> ByteString -> Set ProgressFlag -> m [Output]
lazyProcessP :: MonadIO m => FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> ByteString -> Set ProgressFlag -> m [Output]

-- | Run a task and return the elapsed time along with its result.
timeTask :: MonadIO m => m a -> m (a, NominalDiffTime)

-- | Perform a task, print the elapsed time it took, and return the result.
showElapsed :: MonadIO m => String -> m a -> m a

-- | Unit tests.
tests :: [Test]
lazyCommandV :: MonadIO m => String -> ByteString -> m [Output]
lazyProcessV :: MonadIO m => FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> ByteString -> m [Output]
lazyCommandF :: MonadIO m => String -> ByteString -> m [Output]
lazyProcessF :: MonadIO m => FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> ByteString -> m [Output]
lazyCommandE :: MonadIO m => String -> ByteString -> m [Output]
lazyProcessE :: MonadIO m => FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> ByteString -> m [Output]
lazyCommandEF :: MonadIO m => String -> ByteString -> m [Output]
lazyProcessEF :: MonadIO m => FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> ByteString -> m [Output]
instance Ord ProgressFlag
instance Eq ProgressFlag


-- | Wrappers around some handy unix shell commands. Please let me know if
--   you think of better module names to hold these functions. -dsf
module System.Unix.Misc
md5sum :: FilePath -> IO String
gzip :: FilePath -> IO ()


-- | functions for mounting, umounting, parsing /proc/mounts, etc
module System.Unix.Mount

-- | <a>umountBelow</a> - unmounts all mount points below <i>belowPath</i>
--   /proc/mounts must be present and readable. Because of the way linux
--   handles changeroots, we can't trust everything we see in /proc/mounts.
--   However, we make the following assumptions:
--   
--   <ol>
--   <li>there is a one-to-one correspondence between the entries in
--   /proc/mounts and the actual mounts, and (2) every mount point we might
--   encounter is a suffix of one of the mount points listed in
--   /proc/mounts (because being in a a chroot doesn't affect
--   /proc/mounts.)</li>
--   </ol>
--   
--   So we can search /proc/mounts for an entry has the mount point we are
--   looking for as a substring, then add the extra text on the right to
--   our path and try to unmount that. Then we start again since nested
--   mounts might have been revealed.
--   
--   For example, suppose we are chrooted into /home/david/environments/sid
--   and we call <a>umountBelow /proc</a>. We might see the mount point
--   /home/david/environments/sid/proc/bus/usb in /proc/mounts, which means
--   we need to run <a>umount /proc/bus/usb</a>.
--   
--   See also: <a>umountSucceeded</a>
umountBelow :: Bool -> FilePath -> IO [(FilePath, (String, String, ExitCode))]

-- | <a>umount</a> - run umount with the specified args NOTE: this function
--   uses exec, so you do <i>not</i> need to shell-escape NOTE: we don't
--   use the umount system call because the system call is not smart enough
--   to update /etc/mtab
umount :: [String] -> IO (String, String, ExitCode)
isMountPoint :: FilePath -> IO Bool


-- | A place to collect and hopefully retire all the random ways of running
--   shell commands that have accumulated over the years.
module System.Unix.ProcessExtra
cmdOutput :: String -> IO (Either ErrorCall ByteString)
cmdOutputStrict :: String -> IO (Either ErrorCall ByteString)
toLazy :: ByteString -> ByteString
toStrict :: ByteString -> ByteString
echoCommand :: String -> ByteString -> IO [Output]

-- | Echo the process arguments and then run the process
echoProcess :: FilePath -> [String] -> ByteString -> IO [Output]
ePutStrBl :: String -> IO ()


-- | Strict process running
module System.Unix.ProcessStrict

-- | <a>simpleProcess</a> - run a process returning (stdout, stderr,
--   exitcode)
--   
--   <i>Warning</i> - stdout and stderr will be read strictly so that we do
--   not deadlock when trying to check the exitcode. Do not try doing
--   something like, <tt>simpleProcess ["yes"]</tt>
--   
--   NOTE: this may still dead-lock because we first strictly read outStr
--   and then errStr. Perhaps we should use forkIO or something?
simpleProcess :: FilePath -> [String] -> IO (String, String, ExitCode)
processResult :: FilePath -> [String] -> IO (Either Int (String, String))
processOutput :: FilePath -> [String] -> IO (Either Int String)
simpleCommand :: String -> IO (String, String, ExitCode)
commandResult :: String -> IO (Either Int (String, String))
commandOutput :: String -> IO (Either Int String)


-- | This module, except for useEnv, is copied from the build-env package.
module System.Unix.Chroot

-- | fchroot runs an IO action inside a chroot fchroot performs a chroot,
--   runs the action, and then restores the original root and working
--   directory. This probably affects the chroot and working directory of
--   all the threads in the process, so... NOTE: will throw IOError if
--   internal chroot fails
fchroot :: FilePath -> IO a -> IO a

-- | The ssh inside of the chroot needs to be able to talk to the running
--   ssh-agent. Therefore we mount --bind the ssh agent socket dir inside
--   the chroot (and umount it when we exit the chroot.
useEnv :: FilePath -> (a -> IO a) -> IO a -> IO a

-- | A function to force the process output by examining it but not
--   printing anything.
forceList :: [a] -> IO [a]

-- | First send the process output to the and then force it.
forceList' :: [Output] -> IO [Output]