createProcess package: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 Handles, or just inherited from the parent (the default.) The details of how to create the process are passed in the CreateProcess record. To make it easier to construct a CreateProcess, the functions proc and shell are supplied that fill in the fields with default values which can be overriden as needed. createProcess returns (mb_stdin_hdl, mb_stdout_hdl, mb_stderr_hdl, ph), where

• if std_in == CreatePipe, then mb_stdin_hdl will be Just h, where h is the write end of the pipe connected to the child process's stdin.
• otherwise, mb_stdin_hdl == Nothing

Similarly for mb_stdout_hdl and mb_stderr_hdl. For example, to execute a simple ls command:

r <- createProcess (proc "ls" [])

To create a pipe from which to read the output of ls:

(_, Just hout, _, _) <-
createProcess (proc "ls" []){ std_out = CreatePipe }

To also set the directory in which to run ls:

(_, Just hout, _, _) <-
createProcess (proc "ls" []){ cwd = Just "/home/bob",
std_out = CreatePipe }

Note that Handles provided for std_in, std_out, or std_err via the UseHandle constructor will be closed by calling this function. This is not always the desired behavior. In cases where you would like to leave the Handle open after spawning the child process, please use createProcess_ instead. All created Handles are initially in text mode; if you need them to be in binary mode then use hSetBinaryMode. ph contains a handle to the running process. On Windows use_process_jobs can be set in CreateProcess in order to create a Win32 Job object to monitor a process tree's progress. If it is set then that job is also returned inside ph. ph can be used to kill all running sub-processes. This feature has been available since 1.5.0.0.

This function is almost identical to createProcess. The only differences are:

• Handles provided via UseHandle are not closed automatically.
• This function takes an extra String argument to be used in creating error messages.

This function has been available from the System.Process.Internals module for some time, and is part of the System.Process module since version 1.2.1.0.

readCreateProcess works exactly like readProcess except that it lets you pass CreateProcess giving better flexibility.

> readCreateProcess ((shell "pwd") { cwd = Just "/etc/" }) ""
"/etc\n"

Note that Handles provided for std_in or std_out via the CreateProcess record will be ignored.

readCreateProcessWithExitCode works exactly like readProcessWithExitCode except that it lets you pass CreateProcess giving better flexibility. Note that Handles provided for std_in, std_out, or std_err via the CreateProcess record will be ignored.

A bracket-style resource handler for createProcess. Does automatic cleanup when the action finishes. If there is an exception in the body then it ensures that the process gets terminated and any CreatePipe Handles are closed. In particular this means that if the Haskell thread is killed (e.g. killThread), that the external process is also terminated. e.g.

withCreateProcess (proc cmd args) { ... }  $ \stdin stdout stderr ph -> do
...

A version of readCreateProcessWithExitCode that communicates with the child process through a pair of CommunicationHandles. Example usage:

readCreateProcessWithExitCodeCommunicationHandle
(\(chTheyRead, chTheyWrite) -> proc "child-exe" [show chTheyRead, show chTheyWrite])
(\ hWeRead -> hGetContents hWeRead)
(\ hWeWrite -> hPut hWeWrite "xyz")

where child-exe is a separate executable that is implemented as:

main = do
[chRead, chWrite] <- getArgs
hRead  <- openCommunicationHandleRead  $ read chRead
hWrite <- openCommunicationHandleWrite $ read chWrite
input <- hGetContents hRead
hPut hWrite $ someFn input
hClose hWrite