System.Process

Operations for creating and interacting with sub-processes.

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

createProcess_

Arguments

:: String

Function name (for error messages).

This can be any String, but will typically be the name of the caller. E.g., spawnProcess passes "spawnProcess" here when calling createProcess_.

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

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: 1.2.1.0

shell :: String -> CreateProcess

Construct a CreateProcess record for passing to createProcess, representing a command to be passed to the 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.

data CreateProcess

Constructors

CreateProcess

Fields

• cmdspec :: CmdSpec

  Executable & arguments, or shell command. If cwd is Nothing, relative paths are resolved with respect to the current working directory. If cwd is provided, it is implementation-dependent whether relative paths are resolved with respect to cwd or the current working directory, so absolute paths should be used to ensure portability.

• cwd :: Maybe FilePath

  Optional path to the working directory for the new process

• env :: Maybe [(String, String)]

  Optional environment (otherwise inherit from the current process)

• std_in :: StdStream

  How to determine stdin

• std_out :: StdStream

  How to determine stdout

• std_err :: StdStream

  How to determine stderr

• close_fds :: Bool

  Close all file descriptors except stdin, stdout and stderr in the new process (on Windows, only works if std_in, std_out, and std_err are all Inherit). This implementation will call close on every fd from 3 to the maximum of open files, which can be slow for high maximum of open files. XXX verify what happens with fds in nodejs child processes

• create_group :: Bool

  Create a new process group. On JavaScript this also creates a new session.

• delegate_ctlc :: Bool

  Delegate control-C handling. Use this for interactive console processes to let them handle control-C themselves (see below for details).

  Since: 1.2.0.0

• detach_console :: Bool

  Use the windows DETACHED_PROCESS flag when creating the process; does nothing on other platforms.

  Since: 1.3.0.0

• create_new_console :: Bool

  Use the windows CREATE_NEW_CONSOLE flag when creating the process; does nothing on other platforms.

  Default: False

  Since: 1.3.0.0

• new_session :: Bool

  Use posix setsid to start the new process in a new session; starts process in a new session on JavaScript; does nothing on other platforms.

  Since: 1.3.0.0

• child_group :: Maybe GroupID

  Use posix setgid to set child process's group id; works for JavaScript when system running nodejs is posix. does nothing on other platforms.

  Default: Nothing

  Since: 1.4.0.0

• child_user :: Maybe UserID

  Use posix setuid to set child process's user id; works for JavaScript when system running nodejs is posix. does nothing on other platforms.

  Default: Nothing

  Since: 1.4.0.0

• use_process_jobs :: Bool

  On Windows systems this flag indicates that we should wait for the entire process tree to finish before unblocking. On POSIX systems this flag is ignored. See $exec-on-windows for details.

  Default: False

  Since: 1.5.0.0

Instances

Show CreateProcess

Defined in System.Process.Common

Methods

showsPrec :: Int -> CreateProcess -> ShowS

show :: CreateProcess -> String

showList :: [CreateProcess] -> ShowS

Eq CreateProcess

Defined in System.Process.Common

Methods

(==) :: CreateProcess -> CreateProcess -> Bool

(/=) :: CreateProcess -> CreateProcess -> Bool

data CmdSpec

Constructors

ShellCommand String

A command line to execute using the shell

RawCommand FilePath [String]

The name of an executable with a list of arguments

The FilePath argument names the executable, and is interpreted according to the platform's standard policy for searching for executables. Specifically:

• on Unix systems the execvp(3) semantics is used, where if the executable filename does not contain a slash (/) then the PATH environment variable is searched for the executable.
• on Windows systems the Win32 CreateProcess semantics is used. Briefly: if the filename does not contain a path, then the directory containing the parent executable is searched, followed by the current directory, then some standard locations, and finally the current PATH. An .exe extension is added if the filename does not already have an extension. For full details see the documentation for the Windows SearchPath API.

Windows does not have a mechanism for passing multiple arguments. When using RawCommand on Windows, the command line is serialised into a string, with arguments quoted separately. Command line parsing is up individual programs, so the default behaviour may not work for some programs. If you are not getting the desired results, construct the command line yourself and use ShellCommand.

Instances

IsString CmdSpec

construct a ShellCommand from a string literal

Since: 1.2.1.0

Defined in System.Process.Common

Methods

fromString :: String -> CmdSpec

Show CmdSpec

Defined in System.Process.Common

Methods

showsPrec :: Int -> CmdSpec -> ShowS

show :: CmdSpec -> String

showList :: [CmdSpec] -> ShowS

Eq CmdSpec

Defined in System.Process.Common

Methods

(==) :: CmdSpec -> CmdSpec -> Bool

(/=) :: CmdSpec -> CmdSpec -> Bool

data StdStream

Constructors

Inherit

Inherit Handle from parent

UseHandle Handle

Use the supplied Handle

CreatePipe

Create a new pipe. The returned Handle will use the default encoding and newline translation mode (just like Handles created by openFile).

NoStream

Close the stream's file descriptor without passing a Handle. On POSIX systems this may lead to strange behavior in the child process because attempting to read or write after the file has been closed throws an error. This should only be used with child processes that don't use the file descriptor at all. If you wish to ignore the child process's output you should either create a pipe and drain it manually or pass a Handle that writes to /dev/null.

Instances

Show StdStream

Defined in System.Process.Common

Methods

showsPrec :: Int -> StdStream -> ShowS

show :: StdStream -> String

showList :: [StdStream] -> ShowS

Eq StdStream

Defined in System.Process.Common

Methods

(==) :: StdStream -> StdStream -> Bool

(/=) :: StdStream -> StdStream -> Bool

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.

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.

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.

Since: 1.2.0.0

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.

Since: 1.2.0.0

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.

Since: 1.2.0.0

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.

Since: 1.2.0.0

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 = Just "/etc/" }) ""
 "/etc\n"

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

Since: 1.2.3.0

readProcess

Arguments

:: FilePath

Filename of the executable (see RawCommand for details)

-> [String]

any arguments

-> String

standard input

-> IO String

stdout

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.

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.

Since: 1.2.3.0

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.

withCreateProcess :: CreateProcess -> (Maybe Handle -> Maybe Handle -> Maybe Handle -> ProcessHandle -> IO a) -> IO a

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: 1.4.3.0

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

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: 1.6.4.0

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

type Pid = CPid

The platform specific type for a process identifier.

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

Since: 1.6.3.0

getPid :: ProcessHandle -> IO (Maybe Pid)

Returns the PID (process ID) of a subprocess.

Nothing is returned if the handle was already closed. Otherwise a PID is returned that remains valid as long as the handle is open. The operating system may reuse the PID as soon as the last handle to the process is closed.

Since: 1.6.3.0

getCurrentPid :: IO Pid

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: 1.6.12.0

Control-C handling on Unix

When running an interactive console process (such as a shell, console-based text editor or ghci), we typically want that process to be allowed to handle Ctl-C keyboard interrupts how it sees fit. For example, while most programs simply quit on a Ctl-C, some handle it specially. To allow this to happen, use the delegate_ctlc = True option in the CreateProcess options.

The gory details:

By default Ctl-C will generate a SIGINT signal, causing a UserInterrupt exception to be sent to the main Haskell thread of your program, which if not specially handled will terminate the program. Normally, this is exactly what is wanted: an orderly shutdown of the program in response to Ctl-C.

Of course when running another interactive program in the console then we want to let that program handle Ctl-C. Under Unix however, Ctl-C sends SIGINT to every process using the console. The standard solution is that while running an interactive program, ignore SIGINT in the parent, and let it be handled in the child process. If that process then terminates due to the SIGINT signal, then at that point treat it as if we had received the SIGINT ourselves and begin an orderly shutdown.

This behaviour is implemented by createProcess (and waitForProcess / getProcessExitCode) when the delegate_ctlc = True option is set. In particular, the SIGINT signal will be ignored until waitForProcess returns (or getProcessExitCode returns a non-Nothing result), so it becomes especially important to use waitForProcess for every processes created.

In addition, in delegate_ctlc mode, waitForProcess and getProcessExitCode will throw a UserInterrupt exception if the process terminated with ExitFailure (-SIGINT). Typically you will not want to catch this exception, but let it propagate, giving a normal orderly shutdown. One detail to be aware of is that the UserInterrupt exception is thrown synchronously in the thread that calls waitForProcess, whereas normally SIGINT causes the exception to be thrown asynchronously to the main thread.

For even more detail on this topic, see "Proper handling of SIGINT/SIGQUIT".

Process completion

Notes about exec on Windows

Note that processes which use the POSIX exec system call (e.g. gcc) require special care on Windows. Specifically, the msvcrt C runtime used frequently on Windows emulates exec in a non-POSIX compliant manner, where the caller will be terminated (with exit code 0) and execution will continue in a new process. As a result, on Windows it will appear as though a child process which has called exec has terminated despite the fact that the process would still be running on a POSIX-compliant platform.

Since many programs do use exec, the process library exposes the use_process_jobs flag to make it possible to reliably detect when such a process completes. When this flag is set a ProcessHandle will not be deemed to be "finished" until all processes spawned by it have terminated (except those spawned by the child with the CREATE_BREAKAWAY_FROM_JOB CreateProcess flag).

Note, however, that, because of platform limitations, the exit code returned by waitForProcess and getProcessExitCode cannot not be relied upon when the child uses exec, even when use_process_jobs is used. Specifically, these functions will return the exit code of the *original child* (which always exits with code 0, since it called exec), not the exit code of the process which carried on with execution after exec. This is different from the behavior prescribed by POSIX but is the best approximation that can be realised under the restrictions of the Windows process model.

waitForProcess :: ProcessHandle -> IO ExitCode

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.

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. May throw UserInterrupt when using delegate_ctlc.

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

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

Interprocess communication

createPipe :: IO (Handle, Handle)

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: 1.2.1.0

createPipeFd :: IO (FD, FD)

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

Since: 1.4.2.0

Old deprecated functions

These functions pre-date createProcess which is much more flexible.

runProcess

Arguments

:: FilePath

Filename of the executable (see RawCommand for details)

-> [String]

Arguments to pass to the executable

-> Maybe FilePath

Optional path to the working directory

-> Maybe [(String, String)]

Optional environment (otherwise inherit)

-> Maybe Handle

Handle to use for stdin (Nothing => use existing stdin)

-> Maybe Handle

Handle to use for stdout (Nothing => use existing stdout)

-> Maybe Handle

Handle to use for stderr (Nothing => use existing stderr)

-> IO ProcessHandle

Runs a raw command, optionally specifying Handles from which to take the stdin, stdout and stderr channels for the new process (otherwise these handles are inherited from the current process).

Any Handles passed to runProcess are placed immediately in the closed state.

Note: consider using the more general createProcess instead of runProcess.

runCommand :: String -> IO ProcessHandle

Runs a command using the shell.

runInteractiveProcess

Arguments

:: FilePath

Filename of the executable (see RawCommand for details)

-> [String]

Arguments to pass to the executable

-> Maybe FilePath

Optional path to the working directory

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

For example, to start a process and feed a string to its stdin:

  (inp,out,err,pid) <- runInteractiveProcess "..."
  forkIO (hPutStr inp str)

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.

system :: String -> IO ExitCode

Computation system cmd returns the exit code produced when the operating system runs the shell command cmd.

This computation may fail with one of the following IOErrorType exceptions:

PermissionDenied

The process has insufficient privileges to perform the operation.

ResourceExhausted

Insufficient resources are available to perform the operation.

UnsupportedOperation

The implementation does not support system calls.

On Windows, system passes the command to the Windows command interpreter (CMD.EXE or COMMAND.COM), hence Unixy shell tricks will not work.

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

rawSystem :: String -> [String] -> IO ExitCode

The computation rawSystem cmd args runs the operating system command cmd in such a way that it receives as arguments the args strings exactly as given, with no funny escaping or shell meta-syntax expansion. It will therefore behave more portably between operating systems than system.

The return codes and possible failures are the same as for system.