process-1.6.1.0: Process libraries

Copyright | (c) The University of Glasgow 2004-2008
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | experimental
Portability | non-portable (requires concurrency)
Safe Haskell | Safe
Language | Haskell2010

System.Process

Contents

- Running sub-processes
  - Simpler functions for common tasks
  - Related utilities
  - Control-C handling on Unix
- Process completion
- Old deprecated functions

Description

Operations for creating and interacting with sub-processes.

Synopsis

- createProcess :: CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
- createProcess_ :: String -> CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
- shell :: String -> CreateProcess
- proc :: FilePath -> [String] -> CreateProcess
- data CreateProcess = CreateProcess {
  - cmdspec :: CmdSpec
  - cwd :: Maybe FilePath
  - env :: Maybe [(String, String)]
  - std_in :: StdStream
  - std_out :: StdStream
  - std_err :: StdStream
  - close_fds :: Bool
  - create_group :: Bool
  - delegate_ctlc :: Bool
  - detach_console :: Bool
  - create_new_console :: Bool
  - new_session :: Bool
  - child_group :: Maybe GroupID
  - child_user :: Maybe UserID
  - use_process_jobs :: Bool
  }
- data CmdSpec
  - = ShellCommand String
  - | RawCommand FilePath [String]
- data StdStream
  - = Inherit
  - | UseHandle Handle
  - | CreatePipe
  - | NoStream
- data ProcessHandle
- callProcess :: FilePath -> [String] -> IO ()
- callCommand :: String -> IO ()
- spawnProcess :: FilePath -> [String] -> IO ProcessHandle
- spawnCommand :: String -> IO ProcessHandle
- readCreateProcess :: CreateProcess -> String -> IO String
- readProcess :: FilePath -> [String] -> String -> IO String
- readCreateProcessWithExitCode :: CreateProcess -> String -> IO (ExitCode, String, String)
- readProcessWithExitCode :: FilePath -> [String] -> String -> IO (ExitCode, String, String)
- withCreateProcess :: CreateProcess -> (Maybe Handle -> Maybe Handle -> Maybe Handle -> ProcessHandle -> IO a) -> IO a
- showCommandForUser :: FilePath -> [String] -> String
- waitForProcess :: ProcessHandle -> IO ExitCode
- getProcessExitCode :: ProcessHandle -> IO (Maybe ExitCode)
- terminateProcess :: ProcessHandle -> IO ()
- interruptProcessGroupOf :: ProcessHandle -> IO ()
- createPipe :: IO (Handle, Handle)
- createPipeFd :: IO (FD, FD)
- runProcess :: FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> Maybe Handle -> Maybe Handle -> Maybe Handle -> IO ProcessHandle
- runCommand :: String -> IO ProcessHandle
- runInteractiveProcess :: FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> IO (Handle, Handle, Handle, ProcessHandle)
- runInteractiveCommand :: String -> IO (Handle, Handle, Handle, ProcessHandle)
- system :: String -> IO ExitCode
- rawSystem :: String -> [String] -> IO ExitCode

# 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 `Handle`s, 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 `Handle`s 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 `Handle`s are initially in text mode; if you need them to be in binary mode then use `hSetBinaryMode`.

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:

- `Handle`s provided via `UseHandle` are not closed automatically.
- This function takes an extra `String` argument to be used in creating error messages.
- `use_process_jobs` can be set in CreateProcess since 1.5.0.0 in order to create an I/O completion port to monitor a process tree's progress on Windows.

The function also returns two new handles: * an I/O Completion Port handle on which events will be signaled. * a Job handle which can be used to kill all running processes.

On POSIX platforms these two new handles will always be Nothing

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)

- create_group :: Bool

  Create a new process group

- delegate_ctlc :: Bool

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

  On Windows this has no effect.

  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; does nothing on other platforms.

  Since: 1.3.0.0

- child_group :: Maybe GroupID

  Use posix setgid to set child process's group id; 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; 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.

  Default: `False`

  Since: 1.5.0.0

Instances

Eq CreateProcess # |
Methods (==) :: CreateProcess -> CreateProcess -> Bool # (/=) :: CreateProcess -> CreateProcess -> Bool #
Show CreateProcess # |
Methods showsPrec :: Int -> CreateProcess -> ShowS Source # show :: CreateProcess -> String Source # showList :: [CreateProcess] -> ShowS Source #

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.

Instances

Eq CmdSpec # |
Methods (==) :: CmdSpec -> CmdSpec -> Bool # (/=) :: CmdSpec -> CmdSpec -> Bool #
Show CmdSpec # |
Methods showsPrec :: Int -> CmdSpec -> ShowS Source # show :: CmdSpec -> String Source # showList :: [CmdSpec] -> ShowS Source #
IsString CmdSpec # | construct a `ShellCommand` from a string literal Since: 1.2.1.0
Methods fromString :: String -> CmdSpec Source #

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 `Handle`s created by `openFile`).
NoStream | No stream handle will be passed

Instances

Eq StdStream # |
Methods (==) :: StdStream -> StdStream -> Bool # (/=) :: StdStream -> StdStream -> Bool #
Show StdStream # |
Methods showsPrec :: Int -> StdStream -> ShowS Source # show :: StdStream -> String Source # showList :: [StdStream] -> ShowS Source #

data ProcessHandle #

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

Note that `Handle`s 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 interactive applications.

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
- 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 `Handle`s 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` `Handle`s 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) { ... }  $ \_ _ _ ph -> do
      ...

Since: 1.4.3.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).

## 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 recieved 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

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

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

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.

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

createPipe :: IO (Handle, Handle) #

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

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 `Handle`s from which to take the `stdin`, `stdout` and `stderr` channels for the new process (otherwise these handles are inherited from the current process).

Any `Handle`s 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 `Handle`s 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 `Handle`s 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`.