Documentation

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.

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.

On Windows a second wait method can be used to block for event completion. This requires two handles. A process job handle and a events handle to monitor.

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.

Since: process-1.2.1.0

Create a pipe for interprocess communication and return a (readEnd, writeEnd) Handle pair.

• WinIO Support

When this function is used with WinIO enabled it's the caller's responsibility to register the handles with the I/O manager. If this is not done the operation will deadlock. Association can be done as follows:

    #if defined(IO_MANAGER_WINIO)
    import GHC.IO.SubSystem ((!))
    import GHC.IO.Handle.Windows (handleToHANDLE)
    import GHC.Event.Windows (associateHandle')
    #endif

    ...

    #if defined (IO_MANAGER_WINIO)
    return () ! (do
      associateHandle' =handleToHANDLE <handle)
    #endif

Only associate handles that you are in charge of read/writing to. Do not associate handles passed to another process. It's the process's reponsibility to register the handle if it supports async access.

Since: process-1.2.1.0

Create a pipe for interprocess communication and return a (readEnd, writeEnd) FD pair.

Since: process-1.4.2.0

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 createProcess and setting the create_group flag

The platform specific type for a process identifier.

This is always an integral type. Width and signedness are platform specific.

Since: process-1.6.3.0

Construct a CreateProcess record for passing to createProcess, representing a raw command with arguments.

See RawCommand for precise semantics of the specified FilePath.

Construct a CreateProcess record for passing to createProcess, representing a command to be passed to the shell.

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

Since: process-1.4.3.0

Cleans up the process.

This function is meant to be invoked from any application level cleanup handler. It terminates the process, and closes any CreatePipe handles.

Since: process-1.6.4.0

Creates a new process to run the specified raw command with the given arguments. It does not wait for the program to finish, but returns the ProcessHandle.

Since: process-1.2.0.0

Creates a new process to run the specified command with the given arguments, and wait for it to finish. If the command returns a non-zero exit code, an exception is raised.

If an asynchronous exception is thrown to the thread executing callProcess, the forked process will be terminated and callProcess will wait (block) until the process has been terminated.

Since: process-1.2.0.0

Creates a new process to run the specified shell command. If the command returns a non-zero exit code, an exception is raised.

If an asynchronous exception is thrown to the thread executing callCommand, the forked process will be terminated and callCommand will wait (block) until the process has been terminated.

Since: process-1.2.0.0

readProcess forks an external process, reads its standard output strictly, blocking until the process terminates, and returns the output string. The external process inherits the standard error.

If an asynchronous exception is thrown to the thread executing readProcess, the forked process will be terminated and readProcess will wait (block) until the process has been terminated.

Output is returned strictly, so this is not suitable for launching processes that require interaction over the standard file streams.

This function throws an IOError if the process ExitCode is anything other than ExitSuccess. If instead you want to get the ExitCode then use readProcessWithExitCode.

Users of this function should compile with -threaded if they want other Haskell threads to keep running while waiting on the result of readProcess.

 > readProcess "date" [] []
 "Thu Feb  7 10:03:39 PST 2008\n"

The arguments are:

• The command to run, which must be in the $PATH, or an absolute or relative path
• A list of separate command line arguments to the program. See RawCommand for further discussion of Windows semantics.
• A string to pass on standard input to the forked process.

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.

Since: process-1.2.3.0

Given a program p and arguments args, showCommandForUser p args returns a string suitable for pasting into /bin/sh (on Unix systems) or CMD.EXE (on Windows).

Returns the PID (process ID) of the current process. On POSIX systems, this calls getProcessID from System.Posix.Process in the unix package. On Windows, this calls getCurrentProcessId from System.Win32.Process in the Win32 package.

Since: process-1.6.12.0

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

On Unix systems, terminateProcess sends the process the SIGTERM signal. On Windows systems, if use_process_jobs is True then the Win32 TerminateJobObject function is called to kill all processes associated with the job and passing the exit code of 1 to each of them. Otherwise if use_process_jobs is False then the Win32 TerminateProcess function is called, passing an exit code of 1.

Note: on Windows, if the process was a shell command created by createProcess with shell, or created by runCommand or runInteractiveCommand, then terminateProcess will only terminate the shell, not the command itself. On Unix systems, both processes are in a process group and will be terminated together.

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.

Waits for the specified process to terminate, and returns its exit code. On Unix systems, may throw UserInterrupt when using delegate_ctlc.

GHC Note: in order to call waitForProcess without blocking all the other threads in the system, you must compile the program with -threaded.

Note that it is safe to call waitForProcess for the same process in multiple threads. When the process ends, threads blocking on this call will wake in FIFO order. When using delegate_ctlc and the process is interrupted, only the first waiting thread will throw UserInterrupt.

(Since: 1.2.0.0) On Unix systems, a negative value ExitFailure -signum indicates that the child was terminated by signal signum. The signal numbers are platform-specific, so to test for a specific signal use the constants provided by System.Posix.Signals in the unix package. Note: core dumps are not reported, use System.Posix.Process if you need this detail.

This is a non-blocking version of waitForProcess. If the process is still running, Nothing is returned. If the process has exited, then Just e is returned where e is the exit code of the process.

On Unix systems, see waitForProcess for the meaning of exit codes when the process died as the result of a signal. May throw UserInterrupt when using delegate_ctlc.

This is a non-blocking version of waitForProcess. If the process is still running, Nothing is returned. If the process has exited, then Just e is returned where e is the exit code of the process.

On Unix systems, see waitForProcess for the meaning of exit codes when the process died as the result of a signal. May throw UserInterrupt when using delegate_ctlc.