-- 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.36

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


-- | 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


-- | 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 :: 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)


-- | Control the progress reporting and output of subprocesses.
module System.Unix.Progress

-- | A monad for controlling progress reporting of subprocesses.
type Progress m a = MonadIO m => StateT ProgressState m a

-- | 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
EchoOnFail :: ProgressFlag
AllOnFail :: ProgressFlag
ErrorsOnFail :: ProgressFlag
ResultOnFail :: ProgressFlag
ExceptionOnFail :: ProgressFlag

-- | Create a function that returns the flags used for a given quietness
--   level.
quietnessLevels :: [Set ProgressFlag] -> Int -> Set ProgressFlag

-- | Run the Progress monad with the given flags. The flag set is compute
--   from the current quietness level, &lt;= 0 the most verbose and &gt;= 3
--   the least.
runProgress :: MonadIO m => (Int -> Set ProgressFlag) -> Progress m a -> m a
lazyCommandP :: MonadIO m => (Int -> Set ProgressFlag) -> String -> ByteString -> m [Output]
lazyProcessP :: MonadIO m => (Int -> Set ProgressFlag) -> FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> ByteString -> m [Output]

-- | Look for occurrences of -v and -q in the command line arguments and
--   the current values of environment variables VERBOSITY and QUIETNESS to
--   compute a new value for QUIETNESS. If you want to ignore the current
--   QUIETNESS value say <tt>setQuietness 0 &gt;&gt; computeQuietness</tt>.
defaultQuietness :: MonadIO m => m Int

-- | Perform a task with the given quietness level.
modQuietness :: MonadIO m => (Int -> Int) -> m a -> m a

-- | Do an IO task with additional -v or -q arguments so that the progress
--   reporting becomes more or less verbose.
quieter :: MonadIO m => Int -> m a -> m a

-- | 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

-- | Send a string to stderr.
ePutStr :: MonadIO m => String -> m ()

-- | <tt>ePutStr</tt> with a terminating newline.
ePutStrLn :: MonadIO m => String -> 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 ()

-- | Print a message and return the second argument unevaluated.
eMessage :: MonadIO m => String -> a -> m a

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

-- | <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

-- | Unit tests.
tests :: [Test]
defaultLevels :: [Set ProgressFlag]
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]
lazyCommandD :: MonadIO m => String -> ByteString -> m [Output]
lazyCommandQ :: MonadIO m => String -> ByteString -> m [Output]
lazyCommandS :: MonadIO m => String -> ByteString -> m [Output]
lazyCommandSF :: MonadIO m => 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 ()


-- | 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