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


-- | Process libraries
--   
--   This package contains libraries for dealing with system processes.
@package process
@version 1.1.0.1


-- | Operations for creating and interacting with sub-processes.
module System.Process

-- | This is the most general way to spawn an external process. The process
--   can be a command line to be executed by a shell or a raw command with
--   a list of arguments. The stdin, stdout, and stderr streams of the new
--   process may individually be attached to new pipes, to existing
--   <a>Handle</a>s, or just inherited from the parent (the default.)
--   
--   The details of how to create the process are passed in the
--   <a>CreateProcess</a> record. To make it easier to construct a
--   <a>CreateProcess</a>, the functions <a>proc</a> and <a>shell</a> are
--   supplied that fill in the fields with default values which can be
--   overriden as needed.
--   
--   <a>createProcess</a> returns <tt>(mb_stdin_hdl, mb_stdout_hdl,
--   mb_stderr_hdl, p)</tt>, where
--   
--   <ul>
--   <li>if <tt>std_in == CreatePipe</tt>, then <tt>mb_stdin_hdl</tt> will
--   be <tt>Just h</tt>, where <tt>h</tt> is the write end of the pipe
--   connected to the child process's <tt>stdin</tt>.</li>
--   <li>otherwise, <tt>mb_stdin_hdl == Nothing</tt></li>
--   </ul>
--   
--   Similarly for <tt>mb_stdout_hdl</tt> and <tt>mb_stderr_hdl</tt>.
--   
--   For example, to execute a simple <tt>ls</tt> command:
--   
--   <pre>
--   r &lt;- createProcess (proc "ls" [])
--   </pre>
--   
--   To create a pipe from which to read the output of <tt>ls</tt>:
--   
--   <pre>
--   (_, Just hout, _, _) &lt;-
--       createProcess (proc "ls" []){ std_out = CreatePipe }
--   </pre>
--   
--   To also set the directory in which to run <tt>ls</tt>:
--   
--   <pre>
--   (_, Just hout, _, _) &lt;-
--       createProcess (proc "ls" []){ cwd = Just "\home\bob",
--                                     std_out = CreatePipe }
--   </pre>
createProcess :: CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)

-- | Construct a <a>CreateProcess</a> record for passing to
--   <a>createProcess</a>, representing a command to be passed to the
--   shell.
shell :: String -> CreateProcess

-- | Construct a <a>CreateProcess</a> record for passing to
--   <a>createProcess</a>, representing a raw command with arguments.
proc :: FilePath -> [String] -> CreateProcess
data CreateProcess
CreateProcess :: CmdSpec -> Maybe FilePath -> Maybe [(String, String)] -> StdStream -> StdStream -> StdStream -> Bool -> Bool -> CreateProcess

-- | Executable &amp; arguments, or shell command
cmdspec :: CreateProcess -> CmdSpec

-- | Optional path to the working directory for the new process
cwd :: CreateProcess -> Maybe FilePath

-- | Optional environment (otherwise inherit from the current process)
env :: CreateProcess -> Maybe [(String, String)]

-- | How to determine stdin
std_in :: CreateProcess -> StdStream

-- | How to determine stdout
std_out :: CreateProcess -> StdStream

-- | How to determine stderr
std_err :: CreateProcess -> StdStream

-- | Close all file descriptors except stdin, stdout and stderr in the new
--   process (on Windows, only works if std_in, std_out, and std_err are
--   all Inherit)
close_fds :: CreateProcess -> Bool

-- | Create a new process group
create_group :: CreateProcess -> Bool
data CmdSpec

-- | a command line to execute using the shell
ShellCommand :: String -> CmdSpec

-- | the filename of an executable with a list of arguments
RawCommand :: FilePath -> [String] -> CmdSpec
data StdStream

-- | Inherit Handle from parent
Inherit :: StdStream

-- | Use the supplied Handle
UseHandle :: Handle -> StdStream

-- | Create a new pipe. The returned <tt>Handle</tt> will use the default
--   encoding and newline translation mode (just like <tt>Handle</tt>s
--   created by <tt>openFile</tt>).
CreatePipe :: StdStream
data ProcessHandle

-- | Runs a command using the shell.
runCommand :: String -> IO ProcessHandle

-- | Runs a raw command, optionally specifying <a>Handle</a>s from which to
--   take the <tt>stdin</tt>, <tt>stdout</tt> and <tt>stderr</tt> channels
--   for the new process (otherwise these handles are inherited from the
--   current process).
--   
--   Any <a>Handle</a>s passed to <a>runProcess</a> are placed immediately
--   in the closed state.
--   
--   Note: consider using the more general <a>createProcess</a> instead of
--   <a>runProcess</a>.
runProcess :: FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> Maybe Handle -> Maybe Handle -> Maybe Handle -> IO ProcessHandle

-- | Runs a command using the shell, and returns <a>Handle</a>s that may be
--   used to communicate with the process via its <tt>stdin</tt>,
--   <tt>stdout</tt>, and <tt>stderr</tt> respectively. The <a>Handle</a>s
--   are initially in binary mode; if you need them to be in text mode then
--   use <a>hSetBinaryMode</a>.
runInteractiveCommand :: String -> IO (Handle, Handle, Handle, ProcessHandle)

-- | Runs a raw command, and returns <a>Handle</a>s that may be used to
--   communicate with the process via its <tt>stdin</tt>, <tt>stdout</tt>
--   and <tt>stderr</tt> respectively.
--   
--   For example, to start a process and feed a string to its stdin:
--   
--   <pre>
--   (inp,out,err,pid) &lt;- runInteractiveProcess "..."
--   forkIO (hPutStr inp str)
--   </pre>
--   
--   The <a>Handle</a>s are initially in binary mode; if you need them to
--   be in text mode then use <a>hSetBinaryMode</a>.
runInteractiveProcess :: FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> IO (Handle, Handle, Handle, ProcessHandle)

-- | readProcess forks an external process, reads its standard output
--   strictly, blocking until the process terminates, and returns the
--   output string.
--   
--   Output is returned strictly, so this is not suitable for interactive
--   applications.
--   
--   This function throws an <a>IOError</a> if the process <a>ExitCode</a>
--   is anything other than <a>ExitSuccess</a>.
--   
--   Users of this function should compile with <tt>-threaded</tt> if they
--   want other Haskell threads to keep running while waiting on the result
--   of readProcess.
--   
--   <pre>
--   &gt; readProcess "date" [] []
--   "Thu Feb  7 10:03:39 PST 2008\n"
--   </pre>
--   
--   The arguments are:
--   
--   <ul>
--   <li>The command to run, which must be in the $PATH, or an absolute
--   path</li>
--   <li>A list of separate command line arguments to the program</li>
--   <li>A string to pass on the standard input to the program.</li>
--   </ul>
readProcess :: FilePath -> [String] -> String -> IO String

-- | readProcessWithExitCode creates an external process, reads its
--   standard output and standard error strictly, waits until the process
--   terminates, and then returns the <a>ExitCode</a> of the process, the
--   standard output, and the standard error.
--   
--   <a>readProcess</a> and <a>readProcessWithExitCode</a> are fairly
--   simple wrappers around <a>createProcess</a>. Constructing variants of
--   these functions is quite easy: follow the link to the source code to
--   see how <a>readProcess</a> is implemented.
readProcessWithExitCode :: FilePath -> [String] -> String -> IO (ExitCode, String, String)

-- | Computation <tt>system cmd</tt> returns the exit code produced when
--   the operating system runs the shell command <tt>cmd</tt>.
--   
--   This computation may fail with
--   
--   <ul>
--   <li><tt>PermissionDenied</tt>: The process has insufficient privileges
--   to perform the operation.</li>
--   <li><tt>ResourceExhausted</tt>: Insufficient resources are available
--   to perform the operation.</li>
--   <li><tt>UnsupportedOperation</tt>: The implementation does not support
--   system calls.</li>
--   </ul>
--   
--   On Windows, <a>system</a> passes the command to the Windows command
--   interpreter (<tt>CMD.EXE</tt> or <tt>COMMAND.COM</tt>), hence Unixy
--   shell tricks will not work.
system :: String -> IO ExitCode

-- | The computation <tt><a>rawSystem</a> cmd args</tt> runs the operating
--   system command <tt>cmd</tt> in such a way that it receives as
--   arguments the <tt>args</tt> strings exactly as given, with no funny
--   escaping or shell meta-syntax expansion. It will therefore behave more
--   portably between operating systems than <a>system</a>.
--   
--   The return codes and possible failures are the same as for
--   <a>system</a>.
rawSystem :: String -> [String] -> IO ExitCode

-- | Given a program <tt>p</tt> and arguments <tt>args</tt>,
--   <tt>showCommandForUser p args</tt> returns a string suitable for
--   pasting into sh (on POSIX OSs) or cmd.exe (on Windows).
showCommandForUser :: FilePath -> [String] -> String

-- | Waits for the specified process to terminate, and returns its exit
--   code.
--   
--   GHC Note: in order to call <tt>waitForProcess</tt> without blocking
--   all the other threads in the system, you must compile the program with
--   <tt>-threaded</tt>.
waitForProcess :: ProcessHandle -> IO ExitCode

-- | This is a non-blocking version of <a>waitForProcess</a>. If the
--   process is still running, <a>Nothing</a> is returned. If the process
--   has exited, then <tt><a>Just</a> e</tt> is returned where <tt>e</tt>
--   is the exit code of the process.
getProcessExitCode :: ProcessHandle -> IO (Maybe ExitCode)

-- | Attempts to terminate the specified process. This function should not
--   be used under normal circumstances - no guarantees are given regarding
--   how cleanly the process is terminated. To check whether the process
--   has indeed terminated, use <a>getProcessExitCode</a>.
--   
--   On Unix systems, <a>terminateProcess</a> sends the process the SIGTERM
--   signal. On Windows systems, the Win32 <tt>TerminateProcess</tt>
--   function is called, passing an exit code of 1.
--   
--   Note: on Windows, if the process was a shell command created by
--   <a>createProcess</a> with <a>shell</a>, or created by
--   <a>runCommand</a> or <a>runInteractiveCommand</a>, then
--   <a>terminateProcess</a> will only terminate the shell, not the command
--   itself. On Unix systems, both processes are in a process group and
--   will be terminated together.
terminateProcess :: ProcessHandle -> IO ()

-- | Sends an interrupt signal to the process group of the given process.
--   
--   On Unix systems, it sends the group the SIGINT signal.
--   
--   On Windows systems, it generates a CTRL_BREAK_EVENT and will only work
--   for processes created using <a>createProcess</a> and setting the
--   <a>create_group</a> flag
interruptProcessGroupOf :: ProcessHandle -> IO ()


-- | Executing an external command.
--   
--   This module provides a simple interface for executing external
--   commands. For a more complex, but more powerful, interface, see the
--   <a>System.Process</a> module.
module System.Cmd

-- | Computation <tt>system cmd</tt> returns the exit code produced when
--   the operating system runs the shell command <tt>cmd</tt>.
--   
--   This computation may fail with
--   
--   <ul>
--   <li><tt>PermissionDenied</tt>: The process has insufficient privileges
--   to perform the operation.</li>
--   <li><tt>ResourceExhausted</tt>: Insufficient resources are available
--   to perform the operation.</li>
--   <li><tt>UnsupportedOperation</tt>: The implementation does not support
--   system calls.</li>
--   </ul>
--   
--   On Windows, <a>system</a> passes the command to the Windows command
--   interpreter (<tt>CMD.EXE</tt> or <tt>COMMAND.COM</tt>), hence Unixy
--   shell tricks will not work.
system :: String -> IO ExitCode

-- | The computation <tt><a>rawSystem</a> cmd args</tt> runs the operating
--   system command <tt>cmd</tt> in such a way that it receives as
--   arguments the <tt>args</tt> strings exactly as given, with no funny
--   escaping or shell meta-syntax expansion. It will therefore behave more
--   portably between operating systems than <a>system</a>.
--   
--   The return codes and possible failures are the same as for
--   <a>system</a>.
rawSystem :: String -> [String] -> IO ExitCode