System.Process

Portability	portable
Stability	experimental
Maintainer	libraries@haskell.org

Contents

Running sub-processes
Waiting for process termination
Creating pipes

Description

Operations for creating and interacting with sub-processes.

Synopsis

data ProcessHandle

runCommand :: String -> IO ProcessHandle

runProcess :: FilePath -> [String] -> Maybe [(String, String)] -> Maybe Handle -> Maybe Handle -> Maybe Handle -> IO ProcessHandle

runInteractiveCommand :: String -> IO (Handle, Handle, Handle, ProcessHandle)

runInteractiveProcess :: FilePath -> [String] -> Maybe [(String, String)] -> IO (Handle, Handle, Handle, ProcessHandle)

commandToProcess :: String -> (FilePath, [String])

waitForProcess :: ProcessHandle -> IO ExitCode

createPipe :: IO (Handle, Handle)

createPipeEx :: IOModeEx -> IO (Handle, Handle)

Running sub-processes

data ProcessHandle

A handle to a process, which can be used to wait for termination of the process using waitForProcess.

None of the process-creation functions in this library wait for termination: they all return a ProcessHandle which may be used to wait for the process later.

runCommand :: String -> IO ProcessHandle

Runs a command using the shell.

runProcess

:: FilePath	Filename of the executable
-> [String]	Arguments to pass to the executable
-> Maybe [(String, String)]	Optional environment (otherwise inherit)
-> Maybe Handle	Handle to use for `stdin`
-> Maybe Handle	Handle to use for `stdout`
-> Maybe Handle	Handle to use for `stderr`
-> IO ProcessHandle
Runs a raw command, optionally specifying Handles from which to take the `stdin`, `stdout` and `stderr` channels for the new process. These Handles may be created by `createPipe`, in order to set up communication channels with the remote process (but see also `runInteractiveProcess` if you want to do this).

runInteractiveCommand :: String -> IO (Handle, Handle, Handle, ProcessHandle)

Runs a command using the shell, and returns Handles that may be used to communicate with the process via its stdin, stdout, and stderr respectively.

runInteractiveProcess

:: FilePath	Filename of the executable
-> [String]	Arguments to pass to the executable
-> Maybe [(String, String)]	Optional environment (otherwise inherit)
-> IO (Handle, Handle, Handle, ProcessHandle)
Runs a raw command, and returns Handles that may be used to communicate with the process via its `stdin`, `stdout` and `stderr` respectively. `runInteractiveProcess` can be implemented in terms of `runProcess` and `createPipe`, but it is recommended that you use `runInteractiveCommand` directly if possible since it is likely to be more efficient than combining the lower-level operations.

commandToProcess :: String -> (FilePath, [String])

Turns a shell command into a raw command. Usually this involves wrapping it in an invocation of the shell.

Waiting for process termination

waitForProcess :: ProcessHandle -> IO ExitCode

Waits for the specified process to terminate, and returns its exit code.

Creating pipes

createPipe :: IO (Handle, Handle)

Creates an anonymous pipe and returns a pair of handles, the first for reading and the second for writing. Both pipe ends can be inherited by a child process.

 createPipe  = createPipeEx (BinaryMode AppendMode)

createPipeEx :: IOModeEx -> IO (Handle, Handle)

(createPipeEx modeEx) creates an anonymous pipe and returns a pair of handles, the first for reading and the second for writing. The pipe mode modeEx can be:

TextMode mode -- the pipe is opened in text mode.
BinaryMode mode -- the pipe is opened in binary mode.

The mode determines if child processes can inherit the pipe handles:

ReadMode -- The read handle of the pipe is private to this process.
WriteMode -- The write handle of the pipe is private to this process.
ReadWriteMode -- Both handles are private to this process.
AppendMode -- Both handles are available (inheritable) to child processes. This mode can be used to append (|) two seperate child processes.

If a broken pipe is read, an end-of-file (EOF) exception is raised. If a broken pipe is written to, an invalid argument exception is raised (InvalidArgument).

Produced by Haddock version 0.4