-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Process libraries -- -- This package contains libraries for dealing with system processes. -- -- The typed-process package is a more recent take on a process API, -- which uses this package internally. It features better binary support, -- easier concurrency, and a more composable API. You can read more about -- it at https://github.com/fpco/typed-process/#readme. @package process @version 1.6.8.2 -- | Note: This module exports internal implementation details that -- may change anytime. If you want a more stable API, use -- System.Process instead. module System.Process.Internals data ProcessHandle ProcessHandle :: !MVar ProcessHandle__ -> !Bool -> !MVar () -> ProcessHandle [phandle] :: ProcessHandle -> !MVar ProcessHandle__ [mb_delegate_ctlc] :: ProcessHandle -> !Bool [waitpidLock] :: ProcessHandle -> !MVar () -- | 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 ProcessHandle__ OpenHandle :: PHANDLE -> ProcessHandle__ -- | the process [phdlProcessHandle] :: ProcessHandle__ -> PHANDLE OpenExtHandle :: PHANDLE -> PHANDLE -> ProcessHandle__ -- | the process [phdlProcessHandle] :: ProcessHandle__ -> PHANDLE -- | the job containing the process and its subprocesses [phdlJobHandle] :: ProcessHandle__ -> PHANDLE ClosedHandle :: ExitCode -> ProcessHandle__ type PHANDLE = CPid closePHANDLE :: PHANDLE -> IO () mkProcessHandle :: PHANDLE -> Bool -> IO ProcessHandle data CGid type GroupID = CGid type UserID = CUid modifyProcessHandle :: ProcessHandle -> (ProcessHandle__ -> IO (ProcessHandle__, a)) -> IO a withProcessHandle :: ProcessHandle -> (ProcessHandle__ -> IO a) -> IO a data CreateProcess CreateProcess :: CmdSpec -> Maybe FilePath -> Maybe [(String, String)] -> StdStream -> StdStream -> StdStream -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Maybe GroupID -> Maybe UserID -> Bool -> CreateProcess -- | 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. [cmdspec] :: CreateProcess -> CmdSpec -- | Optional path to the working directory for the new process [cwd] :: CreateProcess -> Maybe FilePath -- | Optional environment (otherwise inherit from the current process) [env] :: CreateProcess -> Maybe [(String, String)] -- | How to determine stdin [std_in] :: CreateProcess -> StdStream -- | How to determine stdout [std_out] :: CreateProcess -> StdStream -- | How to determine stderr [std_err] :: CreateProcess -> StdStream -- | 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). This implementation will call close an every fd from 3 -- to the maximum of open files, which can be slow for high maximum of -- open files. [close_fds] :: CreateProcess -> Bool -- | Create a new process group [create_group] :: CreateProcess -> 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. [delegate_ctlc] :: CreateProcess -> Bool -- | Use the windows DETACHED_PROCESS flag when creating the process; does -- nothing on other platforms. [detach_console] :: CreateProcess -> Bool -- | Use the windows CREATE_NEW_CONSOLE flag when creating the process; -- does nothing on other platforms. -- -- Default: False [create_new_console] :: CreateProcess -> Bool -- | Use posix setsid to start the new process in a new session; does -- nothing on other platforms. [new_session] :: CreateProcess -> Bool -- | Use posix setgid to set child process's group id; does nothing on -- other platforms. -- -- Default: Nothing [child_group] :: CreateProcess -> Maybe GroupID -- | Use posix setuid to set child process's user id; does nothing on other -- platforms. -- -- Default: Nothing [child_user] :: CreateProcess -> Maybe UserID -- | 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. See $exec-on-windows for details. -- -- Default: False [use_process_jobs] :: CreateProcess -> Bool data CmdSpec -- | A command line to execute using the shell ShellCommand :: String -> CmdSpec -- | 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: -- -- RawCommand :: FilePath -> [String] -> CmdSpec data StdStream -- | Inherit Handle from parent Inherit :: StdStream -- | Use the supplied Handle UseHandle :: Handle -> StdStream -- | Create a new pipe. The returned Handle will use the default -- encoding and newline translation mode (just like Handles -- created by openFile). CreatePipe :: StdStream -- | 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. NoStream :: StdStream -- | contains the handles returned by a call to createProcess_Internal data ProcRetHandles ProcRetHandles :: Maybe Handle -> Maybe Handle -> Maybe Handle -> ProcessHandle -> ProcRetHandles [hStdInput] :: ProcRetHandles -> Maybe Handle [hStdOutput] :: ProcRetHandles -> Maybe Handle [hStdError] :: ProcRetHandles -> Maybe Handle [procHandle] :: ProcRetHandles -> ProcessHandle -- | This function is almost identical to createProcess. The only -- differences are: -- -- -- -- 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. createProcess_ :: String -> CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) -- | Deprecated: Please do not use this anymore, use the ordinary -- createProcess. If you need the SIGINT handling, use -- delegate_ctlc = True (runGenProcess_ is now just an imperfectly -- emulated stub that probably duplicates or overrides your own signal -- handling). runGenProcess_ :: String -> CreateProcess -> Maybe CLong -> Maybe CLong -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) -- | Turn an existing file descriptor into a Handle. This is used by -- various external libraries to make Handles. -- -- Makes a binary Handle. This is for historical reasons; it should -- probably be a text Handle with the default encoding and newline -- translation instead. fdToHandle :: FD -> IO Handle startDelegateControlC :: IO () endDelegateControlC :: ExitCode -> IO () stopDelegateControlC :: IO () unwrapHandles :: ProcRetHandles -> (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) pPrPr_disableITimers :: IO () c_execvpe :: CString -> Ptr CString -> Ptr CString -> IO CInt ignoreSignal :: CLong defaultSignal :: CLong -- | runInteractiveProcess blocks signals around the fork(). Since -- blocking/unblocking of signals is a global state operation, we need to -- ensure mutual exclusion of calls to runInteractiveProcess. -- This lock is exported so that other libraries which also need to -- fork() (and also need to make the same global state changes) can -- protect their changes with the same lock. See -- https://github.com/haskell/process/pull/154. runInteractiveProcess_lock :: MVar () withFilePathException :: FilePath -> IO a -> IO a withCEnvironment :: [(String, String)] -> (Ptr CString -> IO a) -> IO a translate :: String -> String -- | Create a pipe for interprocess communication and return a -- (readEnd, writeEnd) Handle pair. createPipe :: IO (Handle, Handle) -- | Create a pipe for interprocess communication and return a -- (readEnd, writeEnd) FD pair. createPipeFd :: IO (FD, FD) -- | 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 interruptProcessGroupOf :: ProcessHandle -> IO () -- | Operations for creating and interacting with sub-processes. module System.Process -- | 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 -- -- -- -- 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. createProcess :: CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) -- | This function is almost identical to createProcess. The only -- differences are: -- -- -- -- 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. createProcess_ :: String -> CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) -- | Construct a CreateProcess record for passing to -- createProcess, representing a command to be passed to the -- shell. shell :: 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. proc :: FilePath -> [String] -> CreateProcess data CreateProcess CreateProcess :: CmdSpec -> Maybe FilePath -> Maybe [(String, String)] -> StdStream -> StdStream -> StdStream -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Maybe GroupID -> Maybe UserID -> Bool -> CreateProcess -- | 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. [cmdspec] :: CreateProcess -> CmdSpec -- | Optional path to the working directory for the new process [cwd] :: CreateProcess -> Maybe FilePath -- | Optional environment (otherwise inherit from the current process) [env] :: CreateProcess -> Maybe [(String, String)] -- | How to determine stdin [std_in] :: CreateProcess -> StdStream -- | How to determine stdout [std_out] :: CreateProcess -> StdStream -- | How to determine stderr [std_err] :: CreateProcess -> StdStream -- | 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). This implementation will call close an every fd from 3 -- to the maximum of open files, which can be slow for high maximum of -- open files. [close_fds] :: CreateProcess -> Bool -- | Create a new process group [create_group] :: CreateProcess -> 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. [delegate_ctlc] :: CreateProcess -> Bool -- | Use the windows DETACHED_PROCESS flag when creating the process; does -- nothing on other platforms. [detach_console] :: CreateProcess -> Bool -- | Use the windows CREATE_NEW_CONSOLE flag when creating the process; -- does nothing on other platforms. -- -- Default: False [create_new_console] :: CreateProcess -> Bool -- | Use posix setsid to start the new process in a new session; does -- nothing on other platforms. [new_session] :: CreateProcess -> Bool -- | Use posix setgid to set child process's group id; does nothing on -- other platforms. -- -- Default: Nothing [child_group] :: CreateProcess -> Maybe GroupID -- | Use posix setuid to set child process's user id; does nothing on other -- platforms. -- -- Default: Nothing [child_user] :: CreateProcess -> Maybe UserID -- | 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. See $exec-on-windows for details. -- -- Default: False [use_process_jobs] :: CreateProcess -> Bool data CmdSpec -- | A command line to execute using the shell ShellCommand :: String -> CmdSpec -- | 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: -- -- RawCommand :: FilePath -> [String] -> CmdSpec data StdStream -- | Inherit Handle from parent Inherit :: StdStream -- | Use the supplied Handle UseHandle :: Handle -> StdStream -- | Create a new pipe. The returned Handle will use the default -- encoding and newline translation mode (just like Handles -- created by openFile). CreatePipe :: StdStream -- | 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. NoStream :: StdStream data ProcessHandle -- | 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. callProcess :: FilePath -> [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. callCommand :: String -> IO () -- | 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. spawnProcess :: FilePath -> [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. spawnCommand :: String -> IO ProcessHandle -- | readCreateProcess works exactly like readProcess -- except that it lets you pass CreateProcess giving better -- flexibility. -- -- 
--   > readCreateProcess ((shell "pwd") { cwd = Just "/etc/" }) ""
--   "/etc\n"
--
-- -- Note that Handles provided for std_in or -- std_out via the CreateProcess record will be ignored. readCreateProcess :: CreateProcess -> String -> IO String -- | 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: -- -- readProcess :: FilePath -> [String] -> String -> IO String -- | readCreateProcessWithExitCode works exactly like -- readProcessWithExitCode except that it lets you pass -- CreateProcess giving better flexibility. -- -- Note that Handles provided for std_in, -- std_out, or std_err via the CreateProcess record -- will be ignored. readCreateProcessWithExitCode :: CreateProcess -> String -> IO (ExitCode, String, String) -- | readProcessWithExitCode is like readProcess but with -- two differences: -- -- -- -- On Unix systems, see waitForProcess for the meaning of exit -- codes when the process died as the result of a signal. readProcessWithExitCode :: FilePath -> [String] -> String -> IO (ExitCode, String, String) -- | 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 Handles 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) { ... }  $ \stdin stdout stderr ph -> do
--     ...
--
withCreateProcess :: CreateProcess -> (Maybe Handle -> Maybe Handle -> Maybe Handle -> ProcessHandle -> IO a) -> IO a -- | Cleans up the process. -- -- This function is meant to be invoked from any application level -- cleanup handler. It terminates the process, and closes any -- CreatePipe handles. cleanupProcess :: (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) -> IO () -- | 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). showCommandForUser :: FilePath -> [String] -> String -- | The platform specific type for a process identifier. -- -- This is always an integral type. Width and signedness are platform -- specific. type Pid = CPid -- | Returns the PID (process ID) of a subprocess. -- -- Nothing is returned if the handle was already closed. Otherwise -- a PID is returned that remains valid as long as the handle is open. -- The operating system may reuse the PID as soon as the last handle to -- the process is closed. getPid :: ProcessHandle -> IO (Maybe Pid) -- | 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. waitForProcess :: ProcessHandle -> IO 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. getProcessExitCode :: ProcessHandle -> IO (Maybe ExitCode) -- | 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. terminateProcess :: ProcessHandle -> 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 interruptProcessGroupOf :: ProcessHandle -> IO () -- | Create a pipe for interprocess communication and return a -- (readEnd, writeEnd) Handle pair. createPipe :: IO (Handle, Handle) -- | Create a pipe for interprocess communication and return a -- (readEnd, writeEnd) FD pair. createPipeFd :: IO (FD, FD) -- | 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. runProcess :: FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> Maybe Handle -> Maybe Handle -> Maybe Handle -> IO ProcessHandle -- | Runs a command using the shell. runCommand :: String -> IO 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)
--
runInteractiveProcess :: FilePath -> [String] -> Maybe FilePath -> Maybe [(String, 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. runInteractiveCommand :: String -> IO (Handle, Handle, Handle, ProcessHandle) -- | 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: -- -- -- -- 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. system :: 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. rawSystem :: String -> [String] -> IO ExitCode -- | Executing an external command. -- -- This module provides a simple interface for executing external -- commands. For a more complex, but more powerful, interface, see the -- System.Process module. -- | Deprecated: Use System.Process instead module System.Cmd -- | 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: -- -- -- -- 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. system :: 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. rawSystem :: String -> [String] -> IO ExitCode