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

System.IO.Streams.Process

Description

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

Synopsis

Documentation

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.

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.

runCommand :: String -> IO ProcessHandle #

Runs a command using the shell.

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.

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.

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.

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

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.

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
  • A string to pass on standard input to the forked process.

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.

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.

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

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

Instances details
Eq CmdSpec 
Instance details

Defined in System.Process.Common

Methods

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

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

Show CmdSpec 
Instance details

Defined in System.Process.Common

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 #

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

Instances details
Eq StdStream 
Instance details

Defined in System.Process.Common

Show StdStream 
Instance details

Defined in System.Process.Common

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

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

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