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

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


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

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

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

-- | The process returns a list of objects of type <a>Output</a>. There
--   will be one Result object at 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 :: ByteString -> Process -> IO [Output]

-- | Current verbosity level.
--   
--   Create a process with <a>runInteractiveCommand</a> and run it with
--   <a>lazyRun</a>.
lazyCommand :: String -> ByteString -> IO [Output]

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

-- | Filter everything except stdout from the output list.
stdoutOnly :: [Output] -> ByteString

-- | Filter everything except stderr from the output list.
stderrOnly :: [Output] -> ByteString

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

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

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

-- | Split out and concatenate Stdout
collectStdout :: [Output] -> (ByteString, [Output])

-- | Split out and concatenate Stderr
collectStderr :: [Output] -> (ByteString, [Output])

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

-- | Collect all output, unpack and concatenate.
collectOutputUnpacked :: [Output] -> (String, String, [ExitCode])
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.
exitCodeOnly :: [Output] -> [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


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


-- | A function taken From missingh, which will not build under sid at the
--   moment.
module System.Unix.List
join :: [a] -> [[a]] -> [a]
consperse :: [a] -> [[a]] -> [a]


-- | The function splitFileName is taken from missingh, at the moment
--   missingh will not build under sid.
module System.Unix.FilePath
dirName :: FilePath -> FilePath
baseName :: FilePath -> String
(+/+) :: FilePath -> FilePath -> FilePath

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

-- | Split the path into directory and file name
--   
--   Examples:
--   
--   [Posix]
--   
--   <pre>
--   splitFileName "/"            == ("/",    ".")
--   splitFileName "/foo/bar.ext" == ("/foo", "bar.ext")
--   splitFileName "bar.ext"      == (".",    "bar.ext")
--   splitFileName "/foo/."       == ("/foo", ".")
--   splitFileName "/foo/.."      == ("/foo", "..")
--   </pre>
--   
--   [Windows]
--   
--   <pre>
--   splitFileName "\\"               == ("\\",      "")
--   splitFileName "c:\\foo\\bar.ext" == ("c:\\foo", "bar.ext")
--   splitFileName "bar.ext"          == (".",       "bar.ext")
--   splitFileName "c:\\foo\\."       == ("c:\\foo", ".")
--   splitFileName "c:\\foo\\.."      == ("c:\\foo", "..")
--   </pre>
--   
--   The first case in the Windows examples returns an empty file name.
--   This is a special case because the "\\" path doesn't refer to an
--   object (file or directory) which resides within a directory.
splitFileName :: FilePath -> (String, String)

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