io-streams-1.5.2.2: Simple, composable, and easy-to-use stream I/O

Safe Haskell | None
Language | Haskell2010

System.IO.Streams.Process

Description

A module adapting the functions from System.Process to work with `io-streams`.

Synopsis

- waitForProcess :: ProcessHandle -> IO ExitCode
- createProcess :: CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
- data ProcessHandle
- data StdStream
  - = Inherit
  - | UseHandle Handle
  - | CreatePipe
  - | NoStream
- data CmdSpec
  - = ShellCommand String
  - | RawCommand FilePath [String]
- data CreateProcess = CreateProcess CmdSpec (Maybe FilePath) (Maybe [(String, String)]) StdStream StdStream StdStream Bool Bool Bool Bool Bool Bool (Maybe GroupID) (Maybe UserID) Bool
- interruptProcessGroupOf :: ProcessHandle -> IO ()
- proc :: FilePath -> [String] -> CreateProcess
- shell :: String -> CreateProcess
- readProcess :: FilePath -> [String] -> String -> IO String
- readProcessWithExitCode :: FilePath -> [String] -> String -> IO (ExitCode, String, String)
- showCommandForUser :: FilePath -> [String] -> String
- getProcessExitCode :: ProcessHandle -> IO (Maybe ExitCode)
- terminateProcess :: ProcessHandle -> IO ()
- runCommand :: String -> IO ProcessHandle
- system :: String -> IO ExitCode
- rawSystem :: String -> [String] -> IO ExitCode
- runInteractiveCommand :: String -> IO (OutputStream ByteString, InputStream ByteString, InputStream ByteString, ProcessHandle)
- runInteractiveProcess :: FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> IO (OutputStream ByteString, InputStream ByteString, InputStream ByteString, ProcessHandle)

# Documentation

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.

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

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

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.

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

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

Instances details

Show StdStream |
Instance details Defined in System.Process.Common Methods showsPrec :: Int -> StdStream -> ShowS # show :: StdStream -> String # showList :: [StdStream] -> ShowS #
Eq StdStream |
Instance details Defined in System.Process.Common Methods (==) :: StdStream -> StdStream -> Bool # (/=) :: StdStream -> StdStream -> 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

Instances details

IsString CmdSpec | construct a `ShellCommand` from a string literal Since: process-1.2.1.0
Instance details Defined in System.Process.Common Methods fromString :: String -> CmdSpec #
Show CmdSpec |
Instance details Defined in System.Process.Common Methods showsPrec :: Int -> CmdSpec -> ShowS # show :: CmdSpec -> String # showList :: [CmdSpec] -> ShowS #
Eq CmdSpec |
Instance details Defined in System.Process.Common Methods (==) :: CmdSpec -> CmdSpec -> Bool # (/=) :: CmdSpec -> CmdSpec -> Bool #

data CreateProcess #

Constructors

CreateProcess CmdSpec (Maybe FilePath) (Maybe [(String, String)]) StdStream StdStream StdStream Bool Bool Bool Bool Bool Bool (Maybe GroupID) (Maybe UserID) Bool |

#### Instances

Instances details

Show CreateProcess |
Instance details Defined in System.Process.Common Methods showsPrec :: Int -> CreateProcess -> ShowS # show :: CreateProcess -> String # showList :: [CreateProcess] -> ShowS #
Eq CreateProcess |
Instance details Defined in System.Process.Common Methods (==) :: CreateProcess -> CreateProcess -> Bool # (/=) :: CreateProcess -> CreateProcess -> Bool #

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

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

shell :: String -> CreateProcess #

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

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.

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.

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

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.

runCommand :: String -> IO ProcessHandle #

Runs a command using the shell.

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

runInteractiveCommand :: String -> IO (OutputStream ByteString, InputStream ByteString, InputStream ByteString, ProcessHandle) #

Runs a command using the shell, and returns streams that may be used to communicate with the process via its stdin, stdout, and stderr respectively.

The streams returned by this command are guarded by locks and are therefore safe to use in multithreaded code.

Since: 1.0.2.0

runInteractiveProcess #

Arguments

:: FilePath | Filename of the executable (see `proc` 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 (OutputStream ByteString, InputStream ByteString, InputStream ByteString, ProcessHandle) |

Runs a raw command, and returns streams 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 (Streams.write (Just str) inp)

The streams returned by this command are guarded by locks and are therefore safe to use in multithreaded code.

Since: 1.0.2.0