Sys.Process

Documentation

data ProcessHandle :: *

Running sub-processes

createProcess :: CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)

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.

see createProcess.

createProcess_

Arguments

:: String

function name (for error messages)

-> CreateProcess

-> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)

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.

see createProcess_.

createProcessHandle :: CreateProcess -> IO ProcessHandle

createWaitProcess :: CreateProcess -> IO ExitCode

createMakeWaitProcess :: CreateProcess -> IO ExitCode

shell :: String -> CreateProcess

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

see shell.

proc :: FilePath -> [String] -> CreateProcess

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

See RawCommand for precise semantics of the specified FilePath.

see proc.

procIn

Arguments

:: FilePath

the working directory

-> FilePath

-> [String]

-> CreateProcess

Simpler functions for common tasks

callProcess :: FilePath -> [String] -> IO ()

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.

see 'System.Process.callProcess.

callCommand :: String -> IO ()

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.

see 'System.Process.callCommand.

spawnProcess :: FilePath -> [String] -> IO ProcessHandle

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.

see 'System.Process.spawnProcess.

spawnCommand :: String -> IO ProcessHandle

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

see 'System.Process.spawnCommand.

readCreateProcess

Arguments

:: CreateProcess

-> String

standard input

-> IO String

stdout

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

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

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

see readCreateProcess.

readProcess

Arguments

:: FilePath

Filename of the executable (see RawCommand for details)

-> [String]

any arguments

-> String

standard input

-> IO String

stdout

readCreateProcessWithExitCode

Arguments

:: CreateProcess

-> String

standard input

-> IO (ExitCode, String, String)

exitcode, stdout, stderr

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.

see readCreateProcessWithExitCode.

readProcessWithExitCode

Arguments

:: FilePath

Filename of the executable (see RawCommand for details)

-> [String]

any arguments

-> String

standard input

-> IO (ExitCode, String, String)

exitcode, stdout, stderr

readProcessWithExitCode is like readProcess but with two differences:

• it returns the ExitCode of the process, and does not throw any exception if the code is not ExitSuccess.
• it reads and returns the output from process' standard error handle, rather than the process inheriting the standard error handle.

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

see readProcessWithExitCode.

Related utilities

showCommandForUser :: FilePath -> [String] -> String

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

see showCommandForUser.

Control-C handling on Unix

waitForProcess :: ProcessHandle -> IO ExitCode

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

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

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.

see waitForProcess.

getProcessExitCode :: ProcessHandle -> IO (Maybe ExitCode)

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.

see getProcessExitCode.

terminateProcess :: ProcessHandle -> IO ()

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

see 'System.Process.terminateProcess.

interruptProcessGroupOf

Arguments

:: ProcessHandle

A process in the process group

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

see 'System.Process.interruptProcessGroupOf.

Interprocess communication

createPipe :: IO (Handle, Handle)

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

see createPipe.