unliftio-0.2.11: The MonadUnliftIO typeclass for unlifting monads to IO (batteries included)

Safe Haskell | Safe
Language | Haskell2010

UnliftIO.Process

Contents

- Running sub-processes
  - Simpler functions for common tasks
  - Related utilities
- Process completion
- Interprocess communication

Description

Unlifted System.Process.

Since: 0.2.5.0

Synopsis

- data CreateProcess = CreateProcess {
  - cmdspec :: CmdSpec
  - cwd :: Maybe FilePath
  - env :: Maybe [(String, String)]
  - std_in :: StdStream
  - std_out :: StdStream
  - std_err :: StdStream
  - close_fds :: Bool
  - create_group :: Bool
  - delegate_ctlc :: Bool
  - detach_console :: Bool
  - create_new_console :: Bool
  - new_session :: Bool
  - child_group :: Maybe GroupID
  - child_user :: Maybe UserID
  - use_process_jobs :: Bool
  }
- data CmdSpec
  - = ShellCommand String
  - | RawCommand FilePath [String]
- data StdStream
  - = Inherit
  - | UseHandle Handle
  - | CreatePipe
  - | NoStream
- data ProcessHandle
- createProcess :: MonadIO m => CreateProcess -> m (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
- createProcess_ :: MonadIO m => String -> CreateProcess -> m (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
- shell :: String -> CreateProcess
- proc :: FilePath -> [String] -> CreateProcess
- callProcess :: MonadIO m => FilePath -> [String] -> m ()
- callCommand :: MonadIO m => String -> m ()
- spawnProcess :: MonadIO m => FilePath -> [String] -> m ProcessHandle
- spawnCommand :: MonadIO m => String -> m ProcessHandle
- readCreateProcess :: MonadIO m => CreateProcess -> String -> m String
- readProcess :: MonadIO m => FilePath -> [String] -> String -> m String
- readCreateProcessWithExitCode :: MonadIO m => CreateProcess -> String -> m (ExitCode, String, String)
- readProcessWithExitCode :: MonadIO m => FilePath -> [String] -> String -> m (ExitCode, String, String)
- withCreateProcess :: MonadUnliftIO m => CreateProcess -> (Maybe Handle -> Maybe Handle -> Maybe Handle -> ProcessHandle -> m a) -> m a
- showCommandForUser :: FilePath -> [String] -> String
- waitForProcess :: MonadIO m => ProcessHandle -> m ExitCode
- getProcessExitCode :: MonadIO m => ProcessHandle -> m (Maybe ExitCode)
- terminateProcess :: MonadIO m => ProcessHandle -> m ()
- interruptProcessGroupOf :: MonadIO m => ProcessHandle -> m ()
- createPipe :: MonadIO m => m (Handle, Handle)
- createPipeFd :: MonadIO m => m (FD, FD)

# Running sub-processes

data CreateProcess Source #

Constructors

CreateProcess |

Fields

- cmdspec :: CmdSpec

  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.

- cwd :: Maybe FilePath

  Optional path to the working directory for the new process

- env :: Maybe [(String, String)]

  Optional environment (otherwise inherit from the current process)

- std_in :: StdStream

  How to determine stdin

- std_out :: StdStream

  How to determine stdout

- std_err :: StdStream

  How to determine stderr

- close_fds :: Bool

  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)

- create_group :: Bool

  Create a new process group

- delegate_ctlc :: 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.

  Since: process-1.2.0.0

- detach_console :: Bool

  Use the windows DETACHED_PROCESS flag when creating the process; does nothing on other platforms.

  Since: process-1.3.0.0

- create_new_console :: Bool

  Use the windows CREATE_NEW_CONSOLE flag when creating the process; does nothing on other platforms.

  Default: `False`

  Since: process-1.3.0.0

- new_session :: Bool

  Use posix setsid to start the new process in a new session; does nothing on other platforms.

  Since: process-1.3.0.0

- child_group :: Maybe GroupID

  Use posix setgid to set child process's group id; does nothing on other platforms.

  Default: `Nothing`

  Since: process-1.4.0.0

- child_user :: Maybe UserID

  Use posix setuid to set child process's user id; does nothing on other platforms.

  Default: `Nothing`

  Since: process-1.4.0.0

- use_process_jobs :: Bool

  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.

  Default: `False`

  Since: process-1.5.0.0

Instances

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

data CmdSpec Source #

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

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

data StdStream Source #

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

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

data ProcessHandle Source #

createProcess :: MonadIO m => CreateProcess -> m (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) Source #

Lifted `createProcess`.

Since: 0.2.5.0

createProcess_ :: MonadIO m => String -> CreateProcess -> m (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) Source #

Lifted `createProcess_`.

Since: 0.2.5.0

shell :: String -> CreateProcess Source #

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

proc :: FilePath -> [String] -> CreateProcess Source #

Construct a `CreateProcess` record for passing to `createProcess`, representing a raw command with arguments.

See `RawCommand` for precise semantics of the specified `FilePath`.

## Simpler functions for common tasks

callProcess :: MonadIO m => FilePath -> [String] -> m () Source #

Lifted `callProcess`.

Since: 0.2.5.0

callCommand :: MonadIO m => String -> m () Source #

Lifted `callCommand`.

Since: 0.2.5.0

spawnProcess :: MonadIO m => FilePath -> [String] -> m ProcessHandle Source #

Lifted `spawnProcess`.

Since: 0.2.5.0

spawnCommand :: MonadIO m => String -> m ProcessHandle Source #

Lifted `spawnCommand`.

Since: 0.2.5.0

readCreateProcess :: MonadIO m => CreateProcess -> String -> m String Source #

Lifted `readCreateProcess`.

Since: 0.2.5.0

readProcess :: MonadIO m => FilePath -> [String] -> String -> m String Source #

Lifted `readProcess`.

Since: 0.2.5.0

readCreateProcessWithExitCode :: MonadIO m => CreateProcess -> String -> m (ExitCode, String, String) Source #

Lifted `readCreateProcessWithExitCode`.

Since: 0.2.5.0

readProcessWithExitCode :: MonadIO m => FilePath -> [String] -> String -> m (ExitCode, String, String) Source #

Lifted `readProcessWithExitCode`.

Since: 0.2.5.0

withCreateProcess :: MonadUnliftIO m => CreateProcess -> (Maybe Handle -> Maybe Handle -> Maybe Handle -> ProcessHandle -> m a) -> m a Source #

Unlifted `withCreateProcess`.

Since: 0.2.5.0

## Related utilities

showCommandForUser :: FilePath -> [String] -> String Source #

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

# Process completion

waitForProcess :: MonadIO m => ProcessHandle -> m ExitCode Source #

Lifted `waitForProcess`.

Since: 0.2.5.0

getProcessExitCode :: MonadIO m => ProcessHandle -> m (Maybe ExitCode) Source #

Lifted `getProcessExitCode`.

Since: 0.2.5.0

terminateProcess :: MonadIO m => ProcessHandle -> m () Source #

Lifted `terminateProcess`.

Since: 0.2.5.0

interruptProcessGroupOf :: MonadIO m => ProcessHandle -> m () Source #

Lifted `interruptProcessGroupOf`.

Since: 0.2.5.0

# Interprocess communication

createPipe :: MonadIO m => m (Handle, Handle) Source #

Lifted `createPipe`.

Since: 0.2.5.0

createPipeFd :: MonadIO m => m (FD, FD) Source #

Lifted `createPipeFd`.

Since: 0.2.5.0