| Portability | non-portable (requires concurrency) |
|---|---|
| Stability | experimental |
| Maintainer | libraries@haskell.org |
| Safe Haskell | Trustworthy |
System.Process
Description
Operations for creating and interacting with sub-processes.
- createProcess :: CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
- shell :: String -> CreateProcess
- proc :: FilePath -> [String] -> CreateProcess
- data CreateProcess = CreateProcess {}
- data CmdSpec
- 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
- showCommandForUser :: FilePath -> [String] -> String
- waitForProcess :: ProcessHandle -> IO ExitCode
- getProcessExitCode :: ProcessHandle -> IO (Maybe ExitCode)
- terminateProcess :: ProcessHandle -> IO ()
- interruptProcessGroupOf :: ProcessHandle -> IO ()
Running sub-processes
createProcess :: CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)Source
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, thenmb_stdin_hdlwill beJust h, wherehis the write end of the pipe connected to the child process'sstdin. - 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 -> CreateProcessSource
Construct a CreateProcess record for passing to createProcess,
representing a command to be passed to the shell.
proc :: FilePath -> [String] -> CreateProcessSource
Construct a CreateProcess record for passing to createProcess,
representing a raw command with arguments.
The FilePath names the executable, and is interpreted according
to the platform's standard policy for searching for
executables. Specifically:
- on Unix systems the
execvpsemantics is used, where if the filename does not contain a slash (/) then thePATHenvironment variable is searched for the executable. - on Windows systems the Win32
CreateProcesssemantics 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 some standard locations, and finally the currentPATH. An.exeextension is added if the filename does not already have an extension. For full details see the documentation for the WindowsSearchPathAPI.
data CreateProcess Source
Constructors
| CreateProcess | |
Fields
| |
Constructors
| ShellCommand String | a command line to execute using the shell |
| RawCommand FilePath [String] | the filename of an executable with a list of arguments.
see |
Constructors
| Inherit | Inherit Handle from parent |
| UseHandle Handle | Use the supplied Handle |
| CreatePipe | Create a new pipe. The returned
|
data ProcessHandle Source
Specific variants of createProcess
runCommand :: String -> IO ProcessHandleSource
Runs a command using the shell.
Arguments
| :: FilePath | Filename of the executable (see |
| -> [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 |
| -> Maybe Handle | Handle to use for |
| -> Maybe Handle | Handle to use for |
| -> 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)Source
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.
Arguments
| :: FilePath | Filename of the executable (see |
| -> [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)
The Handles are initially in binary mode; if you need them to be
in text mode then use hSetBinaryMode.
Arguments
| :: FilePath | Filename of the executable (see |
| -> [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.
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.
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 path
- A list of separate command line arguments to the program
- A string to pass on the standard input to the program.
Arguments
| :: FilePath | Filename of the executable (see |
| -> [String] | any arguments |
| -> String | standard 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.
If an asynchronous exception is thrown to the thread executing
readProcessWithExitCode. The forked process will be terminated and
readProcessWithExitCode will wait (block) until the process has been
terminated.
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 ExitCodeSource
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 ExitCodeSource
The computation runs the operating system command
rawSystem cmd argscmd 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.
showCommandForUser :: FilePath -> [String] -> StringSource
Given a program p and arguments args,
showCommandForUser p args returns a string suitable for pasting
into sh (on POSIX OSs) or cmd.exe (on Windows).
Process completion
waitForProcess :: ProcessHandle -> IO ExitCodeSource
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)Source
This is a non-blocking version of waitForProcess. If the process is
still running, Nothing is returned. If the process has exited, then
is returned where Just ee is the exit code of the process.
terminateProcess :: ProcessHandle -> IO ()Source
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.
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