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.