process-1.6.25.0: Process libraries
Copyright(c) The University of Glasgow 2004
LicenseBSD-style (see the file libraries/base/LICENSE)
Maintainerlibraries@haskell.org
Stabilityexperimental
Portabilityportable
Safe HaskellTrustworthy
LanguageHaskell2010

System.Process.Internals

Description

Note: This module exports internal implementation details that may change anytime. If you want a more stable API, use System.Process instead.

Synopsis

Documentation

data ProcessHandle Source #

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__ Source #

Constructors

OpenHandle 

Fields

OpenExtHandle

OpenExtHandle is only applicable for Windows platform. It represents Job Objects.

Fields

ClosedHandle ExitCode 

data CGid Source #

Instances

Instances details
Storable CGid 
Instance details

Defined in System.Posix.Types

Bits CGid 
Instance details

Defined in System.Posix.Types

FiniteBits CGid 
Instance details

Defined in System.Posix.Types

Bounded CGid 
Instance details

Defined in System.Posix.Types

Enum CGid 
Instance details

Defined in System.Posix.Types

Ix CGid 
Instance details

Defined in System.Posix.Types

Num CGid 
Instance details

Defined in System.Posix.Types

Read CGid 
Instance details

Defined in System.Posix.Types

Integral CGid 
Instance details

Defined in System.Posix.Types

Real CGid 
Instance details

Defined in System.Posix.Types

Show CGid 
Instance details

Defined in System.Posix.Types

Eq CGid 
Instance details

Defined in System.Posix.Types

Methods

(==) :: CGid -> CGid -> Bool #

(/=) :: CGid -> CGid -> Bool #

Ord CGid 
Instance details

Defined in System.Posix.Types

Methods

compare :: CGid -> CGid -> Ordering #

(<) :: CGid -> CGid -> Bool #

(<=) :: CGid -> CGid -> Bool #

(>) :: CGid -> CGid -> Bool #

(>=) :: CGid -> CGid -> Bool #

max :: CGid -> CGid -> CGid #

min :: CGid -> CGid -> CGid #

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). This implementation will call close on every fd from 3 to the maximum of open files, which can be slow for high maximum of open files. XXX verify what happens with fds in nodejs child processes

  • create_group :: Bool

    Create a new process group. On JavaScript this also creates a new session.

  • delegate_ctlc :: Bool

    Delegate control-C handling. Use this for interactive console processes to let them handle control-C themselves (see below for details).

    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; starts process in a new session on JavaScript; 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; works for JavaScript when system running nodejs is posix. 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; works for JavaScript when system running nodejs is posix. 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. See $exec-on-windows for details.

    Default: False

    Since: process-1.5.0.0

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.

Windows does not have a mechanism for passing multiple arguments. When using RawCommand on Windows, the command line is serialised into a string, with arguments quoted separately. Command line parsing is up individual programs, so the default behaviour may not work for some programs. If you are not getting the desired results, construct the command line yourself and use ShellCommand.

Instances

Instances details
IsString CmdSpec Source #

construct a ShellCommand from a string literal

Since: process-1.2.1.0

Instance details

Defined in System.Process.Common

Show CmdSpec Source # 
Instance details

Defined in System.Process.Common

Eq CmdSpec Source # 
Instance details

Defined in System.Process.Common

Methods

(==) :: CmdSpec -> CmdSpec -> Bool #

(/=) :: CmdSpec -> CmdSpec -> Bool #

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

Instances

Instances details
Show StdStream Source # 
Instance details

Defined in System.Process.Common

Eq StdStream Source # 
Instance details

Defined in System.Process.Common

data ProcRetHandles Source #

contains the handles returned by a call to createProcess_Internal

createProcess_ Source #

Arguments

:: String

Function name (for error messages).

This can be any String, but will typically be the name of the caller. E.g., spawnProcess passes "spawnProcess" here when calling createProcess_.

-> CreateProcess 
-> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) 

This function is almost identical to createProcess. The only differences are:

  • Handles provided via UseHandle are not closed automatically.
  • This function takes an extra String argument to be used in creating error messages.

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.

Since: process-1.2.1.0

runGenProcess_ Source #

Arguments

:: String

function name (for error messages)

-> CreateProcess 
-> Maybe CLong

handler for SIGINT

-> Maybe CLong

handler for SIGQUIT

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

fdToHandle :: FD -> IO Handle Source #

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.

runInteractiveProcess_lock :: MVar () Source #

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.

Since: process-1.6.6.0

createPipe :: IO (Handle, Handle) Source #

Create a pipe for interprocess communication and return a (readEnd, writeEnd) Handle pair.

  • WinIO Support

When this function is used with WinIO enabled it's the caller's responsibility to register the handles with the I/O manager. If this is not done the operation will deadlock. Association can be done as follows:

    #if defined(IO_MANAGER_WINIO)
    import GHC.IO.SubSystem ((!))
    import GHC.IO.Handle.Windows (handleToHANDLE)
    import GHC.Event.Windows (associateHandle')
    #endif

    ...

    #if defined (IO_MANAGER_WINIO)
    return () ! (do
      associateHandle' =handleToHANDLE <handle)
    #endif

Only associate handles that you are in charge of read/writing to. Do not associate handles passed to another process. It's the process's reponsibility to register the handle if it supports async access.

Since: process-1.2.1.0

createPipeFd :: IO (FD, FD) Source #

Create a pipe for interprocess communication and return a (readEnd, writeEnd) FD pair.

Since: process-1.4.2.0

interruptProcessGroupOf Source #

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

withForkWait :: IO () -> (IO () -> IO a) -> IO a Source #

Fork a thread while doing something else, but kill it if there's an exception.

This is important in the cases above because we want to kill the thread that is holding the Handle lock, because when we clean up the process we try to close that handle, which could otherwise deadlock.

Since: process-1.6.20.0

ignoreSigPipe :: IO () -> IO () Source #

Handle any SIGPIPE errors in the given computation.

Since: process-1.6.20.0