HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

Moduletyped-process-0.2.13.0Haskell2010

System.Process.Typed

The simplest way to get started with this API is to turn on OverloadedStrings and call runProcess. The following will write the contents of /home to stdout and then print the exit code (on a UNIX system).

{-# LANGUAGE OverloadedStrings #-}

runProcess "ls -l /home" >>= print

Please see the README.md file for more examples of using this API.

  • 9 types
  • 60 values

Types

4 declarations
datadata ProcessConfig stdin stdout stderr
#

An abstract configuration for a process, which can then be launched into an actual running Process. Takes three type parameters, providing the types of standard input, standard output, and standard error, respectively.

There are three ways to construct a value of this type:

  • With the proc smart constructor, which takes a command name and a list of arguments.

  • With the shell smart constructor, which takes a shell string

  • With the IsString instance via OverloadedStrings. If you provide it a string with no spaces (e.g., "date"), it will treat it as a raw command with no arguments (e.g., proc "date" []). If it has spaces, it will use shell.

In all cases, the default for all three streams is to inherit the streams from the parent process. For other settings, see the setters below for default values.

Once you have a ProcessConfig you can launch a process from it using the functions in the section Launch a process.

Instances2Show, IsString
  • Show (ProcessConfig stdin stdout stderr)Defined in typed-process-0.2.13.0 · System.Process.Typed.Internal
  • (stdin ~ (), stdout ~ (), stderr ~ ()) => IsString (ProcessConfig stdin stdout stderr)Defined in typed-process-0.2.13.0 · System.Process.Typed.Internal
datadata StreamSpec (streamType :: StreamType) a
#

A specification for how to create one of the three standard child streams, stdin, stdout and stderr. A StreamSpec can be thought of as containing

  1. A type safe version of StdStream from System.Process. This determines whether the stream should be inherited from the parent process, piped to or from a Handle, etc.

  2. A means of accessing the stream as a value of type a

  3. A cleanup action which will be run on the stream once the process terminates

To create a StreamSpec see the section Stream specs.

Instances2Functor, IsString
  • Functor (StreamSpec streamType)Defined in typed-process-0.2.13.0 · System.Process.Typed.Internal
  • (streamType ~ 'STInput, res ~ ()) => IsString (StreamSpec streamType res)Defined in typed-process-0.2.13.0 · System.Process.Typed.Internal

    This instance uses byteStringInput to convert a raw string into a stream of input for a child process.

datadata StreamType
#

Whether a stream is an input stream or output stream. Note that this is from the perspective of the child process, so that a child's standard input stream is an STInput, even though the parent process will be writing to it.

STInputSTOutput
datadata Process stdin stdout stderr
#

A running process. The three type parameters provide the type of the standard input, standard output, and standard error streams.

To interact with a Process use the functions from the section Interact with a process.

Instances1Show
  • Show (Process stdin stdout stderr)Defined in typed-process-0.2.13.0 · System.Process.Typed

ProcessConfig

0 declarations

Smart constructors

Setters

Stream specs

0 declarations

Built-in stream specs

valueinherit :: StreamSpec anyStreamType ()
#

A stream spec which simply inherits the stream of the parent process.

valuenullStream :: StreamSpec anyStreamType ()
#

A stream spec which is empty when used for for input and discards output. Note this requires your platform's null device to be available when the process is started.

valueclosed :: StreamSpec anyStreamType ()
#

A stream spec which will close the stream for the child process. You usually do not want to use this, as it will leave the corresponding file descriptor unassigned and hence available for re-use in the child process. Prefer nullStream unless you're certain you want this behavior.

valuebyteStringOutput :: StreamSpec 'STOutput (STM ByteString)
#

Capture the output of a process in a ByteString.

This function will fork a separate thread to consume all input from the process, and will only make the results available when the underlying Handle is closed. As this is provided as an STM action, you can either check if the result is available, or block until it's ready.

In the event of any exception occurring when reading from the Handle, the STM action will throw a ByteStringOutputException.

valueuseHandleOpen :: Handle -> StreamSpec anyStreamType ()
#

Use the provided Handle for the child process, and when the process exits, do not close it. This is useful if, for example, you want to have multiple processes write to the same log file sequentially.

Create your own stream spec

valuemkStreamSpec
  1. :: StdStream
  2. -> (ProcessConfig () () () -> Maybe Handle -> IO (a, IO ()))
  3. -> StreamSpec streamType a
#

Create a new StreamSpec from the given StdStream and a helper function. This function:

  • Takes as input the raw Maybe Handle returned by the createProcess function. The handle will be Just Handle if the StdStream argument is CreatePipe and Nothing otherwise. See createProcess for more details.

  • Returns the actual stream value a, as well as a cleanup function to be run when calling stopProcess.

If making a StreamSpec with CreatePipe, prefer mkPipeStreamSpec, which encodes the invariant that a Handle is created.

Launch a process

9 declarations
valuestopProcess :: MonadIO m => Process stdin stdout stderr -> m ()
#

Close a process and release any resources acquired. This will ensure terminateProcess is called, wait for the process to actually exit, and then close out resources allocated for the streams. In the event of any cleanup exceptions being thrown this will throw an exception.

Exception-throwing functions

The functions ending in underbar (_) are the same as their counterparts without underbar but instead of returning an ExitCode they throw ExitCodeException on failure.

Interact with a process

0 declarations

Process exit code

valuecheckExitCode :: MonadIO m => Process stdin stdout stderr -> m ()
#

Wait for a process to exit, and ensure that it exited successfully. If not, throws an ExitCodeException.

Exceptions thrown by this function will not include stdout or stderr (This prevents unbounded memory usage from reading them into memory). However, some callers such as readProcess_ catch the exception, add the stdout and stderr, and rethrow.

Process ID

valuegetPid :: Process stdin stdout stderr -> IO (Maybe Pid)
#

Returns the PID (process ID) of a subprocess.

Nothing is returned if the underlying ProcessHandle 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.

Process streams

valuegetStdin :: Process stdin stdout stderr -> stdin
#

Get the child's standard input stream value.

valuegetStdout :: Process stdin stdout stderr -> stdout
#

Get the child's standard output stream value.

valuegetStderr :: Process stdin stdout stderr -> stderr
#

Get the child's standard error stream value.

Exceptions

4 declarations
datadata ExitCodeException
#

Exception thrown by checkExitCode in the event of a non-success exit code. Note that checkExitCode is called by other functions as well, like runProcess_ or readProcess_.

Note that several functions that throw an ExitCodeException intentionally do not populate eceStdout or eceStderr. This prevents unbounded memory usage for large stdout and stderrs.

Functions which do include eceStdout or eceStderr (like readProcess_) state so in their documentation.

Constructors

Instances2Show, Exception

Re-exports

3 declarations
datadata ExitCode
#

Defines the exit codes that a program can return.

Constructors

  • ExitSuccess

    indicates successful termination;

  • ExitFailure Int

    indicates program failure with an exit code. The exact interpretation of the code is operating-system dependent. In particular, some values may be prohibited (e.g. 0 on a POSIX-compliant system).

Instances8Eq, Ord, Read, Show, Generic, Exception, …
datadata 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.

Instances2Eq, Show
  • Eq StdStreamDefined in process-1.6.26.1 · System.Process.Common
  • Show StdStreamDefined in process-1.6.26.1 · System.Process.Common
typetype Pid = CPid
#

The platform specific type for a process identifier.

This is always an integral type. Width and signedness are platform specific.

Unsafe functions

1 declaration
valueunsafeProcessHandle :: Process stdin stdout stderr -> ProcessHandle
#

Take ProcessHandle out of the Process. This method is needed in cases one need to use low level functions from the process package. Use cases for this method are:

  1. Send a special signal to the process.

  2. Terminate the process group instead of terminating single process.

  3. Use platform specific API on the underlying process.

This method is considered unsafe because the actions it performs on the underlying process may overlap with the functionality that typed-process provides. For example the user should not call waitForProcess on the process handle as either waitForProcess or stopProcess will lock. Additionally, even if process was terminated by the terminateProcess or by sending signal, stopProcess should be called either way in order to cleanup resources allocated by the typed-process.

Deprecated functions

2 declarations