process-1.0.1.0: Process librariesContentsIndex
System.Process
Portabilitynon-portable (requires concurrency)
Stabilityexperimental
Maintainerlibraries@haskell.org
Contents
Running sub-processes
Specific variants of createProcess
Process completion
Description
Operations for creating and interacting with sub-processes.
Synopsis
createProcess :: 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
}
data CmdSpec
= ShellCommand String
| RawCommand FilePath [String]
data StdStream
= Inherit
| UseHandle Handle
| CreatePipe
data ProcessHandle
runCommand :: String -> IO ProcessHandle
runProcess :: FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> Maybe Handle -> Maybe Handle -> Maybe Handle -> IO ProcessHandle
runInteractiveCommand :: String -> IO (Handle, Handle, Handle, ProcessHandle)
runInteractiveProcess :: FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> IO (Handle, Handle, Handle, ProcessHandle)
readProcess :: FilePath -> [String] -> String -> IO String
readProcessWithExitCode :: FilePath -> [String] -> String -> IO (ExitCode, String, String)
system :: String -> IO ExitCode
rawSystem :: String -> [String] -> IO ExitCode
waitForProcess :: ProcessHandle -> IO ExitCode
getProcessExitCode :: ProcessHandle -> IO (Maybe ExitCode)
terminateProcess :: ProcessHandle -> IO ()
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, p), 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 }
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.
data CreateProcess
Constructors
CreateProcess
cmdspec :: CmdSpecExecutable & arguments, or shell command
cwd :: Maybe FilePathOptional path to the working directory for the new process
env :: Maybe [(String, String)]Optional environment (otherwise inherit from the current process)
std_in :: StdStreamHow to determine stdin
std_out :: StdStreamHow to determine stdout
std_err :: StdStreamHow to determine stderr
close_fds :: BoolClose all file descriptors except stdin, stdout and stderr in the new process
data CmdSpec
Constructors
ShellCommand Stringa command line to execute using the shell
RawCommand FilePath [String]the filename of an executable with a list of arguments
data StdStream
Constructors
InheritInherit Handle from parent
UseHandle HandleUse the supplied Handle
CreatePipeCreate a new pipe
data ProcessHandle
Specific variants of createProcess
runCommand :: String -> IO ProcessHandle
Runs a command using the shell.
runProcess
:: FilePathFilename of the executable
-> [String]Arguments to pass to the executable
-> Maybe FilePathOptional path to the working directory
-> Maybe [(String, String)]Optional environment (otherwise inherit)
-> Maybe HandleHandle to use for stdin (Nothing => use existing stdin)
-> Maybe HandleHandle to use for stdout (Nothing => use existing stdout)
-> Maybe HandleHandle 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.

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. The Handles are initially in binary mode; if you need them to be in text mode then use hSetBinaryMode.
runInteractiveProcess
:: FilePathFilename of the executable
-> [String]Arguments to pass to the executable
-> Maybe FilePathOptional 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)

The Handles are initially in binary mode; if you need them to be in text mode then use hSetBinaryMode.

readProcess
:: FilePathcommand to run
-> [String]any arguments
-> Stringstandard input
-> IO Stringstdout + stderr

readProcess forks an external process, reads its standard output strictly, blocking until the process terminates, and returns either the output string, or, in the case of non-zero exit status, an error code, and any output.

Output is returned strictly, so this is not suitable for interactive applications.

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" [] []
  Right "Thu Feb  7 10:03:39 PST 2008\n"

The argumenst are:

  • The command to run, which must be in the $PATH, or an absolute path
  • A list of separate command line arguments to the program
  • A string to pass on the standard input to the program.
readProcessWithExitCode
:: FilePathcommand to run
-> [String]any arguments
-> Stringstandard input
-> IO (ExitCode, String, String)exitcode, stdout, stderr

readProcessWithExitCode creates an external process, reads its standard output and standard error strictly, waits until the process terminates, and then returns the ExitCode of the process, the standard output, and the standard error.

readProcess and readProcessWithExitCode are fairly simple wrappers around createProcess. Constructing variants of these functions is quite easy: follow the link to the source code to see how readProcess is implemented.

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

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

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.

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.

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. Subsequent calls to getProcessExitStatus always return Just ExitSuccess, regardless of what the original exit code was.
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 SIGKILL signal. On Windows systems, the Win32 TerminateProcess function is called, passing an exit code of 1.

Produced by Haddock version 2.3.0