process-1.6.17.0: Process libraries

Copyright | (c) The University of Glasgow 2004
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | experimental
Portability | portable
Safe Haskell | Trustworthy
Language | Haskell2010

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

- data ProcessHandle = ProcessHandle {
  - phandle :: !(MVar ProcessHandle__)
  - mb_delegate_ctlc :: !Bool
  - waitpidLock :: !(MVar ())
  }
- data ProcessHandle__
  - = OpenHandle {
    - phdlProcessHandle :: PHANDLE
    }
  - | OpenExtHandle {
    - phdlProcessHandle :: PHANDLE
    - phdlJobHandle :: PHANDLE
    }
  - | ClosedHandle ExitCode
- 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 :: 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 ProcRetHandles = ProcRetHandles {
  - hStdInput :: Maybe Handle
  - hStdOutput :: Maybe Handle
  - hStdError :: Maybe Handle
  - procHandle :: ProcessHandle
  }
- createProcess_ :: String -> CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
- runGenProcess_ :: String -> CreateProcess -> Maybe CLong -> Maybe CLong -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
- 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_lock :: MVar ()
- withFilePathException :: FilePath -> IO a -> IO a
- withCEnvironment :: [(String, String)] -> (Ptr CString -> IO a) -> IO a
- translate :: String -> String
- createPipe :: IO (Handle, Handle)
- createPipeFd :: IO (FD, FD)
- interruptProcessGroupOf :: ProcessHandle -> IO ()

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

Constructors

ProcessHandle |

Fields

- phandle :: !(MVar ProcessHandle__)
- mb_delegate_ctlc :: !Bool
- waitpidLock :: !(MVar ())

data ProcessHandle__ Source #

Constructors

OpenHandle |

Fields

- phdlProcessHandle :: PHANDLE

  the process

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

Fields

- phdlProcessHandle :: PHANDLE

  the process

- phdlJobHandle :: PHANDLE

  the job containing the process and its subprocesses

ClosedHandle ExitCode |

type PHANDLE = CPid Source #

closePHANDLE :: PHANDLE -> IO () Source #

mkProcessHandle :: PHANDLE -> Bool -> IO ProcessHandle Source #

data CGid Source #

#### Instances

Instances details

Storable CGid |

Instance details

Defined in System.Posix.Types

Methods

sizeOf :: CGid -> Int Source #

alignment :: CGid -> Int Source #

peekElemOff :: Ptr CGid -> Int -> IO CGid Source #

pokeElemOff :: Ptr CGid -> Int -> CGid -> IO () Source #

peekByteOff :: Ptr b -> Int -> IO CGid Source #

pokeByteOff :: Ptr b -> Int -> CGid -> IO () Source #

peek :: Ptr CGid -> IO CGid Source #

poke :: Ptr CGid -> CGid -> IO () Source #

Bits CGid |

Instance details

Defined in System.Posix.Types

Methods

(.&.) :: CGid -> CGid -> CGid Source #

(.|.) :: CGid -> CGid -> CGid Source #

xor :: CGid -> CGid -> CGid Source #

complement :: CGid -> CGid Source #

shift :: CGid -> Int -> CGid Source #

rotate :: CGid -> Int -> CGid Source #

zeroBits :: CGid Source #

bit :: Int -> CGid Source #

setBit :: CGid -> Int -> CGid Source #

clearBit :: CGid -> Int -> CGid Source #

complementBit :: CGid -> Int -> CGid Source #

testBit :: CGid -> Int -> Bool Source #

bitSizeMaybe :: CGid -> Maybe Int Source #

bitSize :: CGid -> Int Source #

isSigned :: CGid -> Bool Source #

shiftL :: CGid -> Int -> CGid Source #

unsafeShiftL :: CGid -> Int -> CGid Source #

shiftR :: CGid -> Int -> CGid Source #

unsafeShiftR :: CGid -> Int -> CGid Source #

rotateL :: CGid -> Int -> CGid Source #

rotateR :: CGid -> Int -> CGid Source #

popCount :: CGid -> Int Source #

FiniteBits CGid |
Instance details Defined in System.Posix.Types Methods finiteBitSize :: CGid -> Int Source # countLeadingZeros :: CGid -> Int Source # countTrailingZeros :: CGid -> Int Source #
Bounded CGid |
Instance details Defined in System.Posix.Types Methods minBound :: CGid Source # maxBound :: CGid Source #
Enum CGid |
Instance details Defined in System.Posix.Types Methods succ :: CGid -> CGid Source # pred :: CGid -> CGid Source # toEnum :: Int -> CGid Source # fromEnum :: CGid -> Int Source # enumFrom :: CGid -> [CGid] Source # enumFromThen :: CGid -> CGid -> [CGid] Source # enumFromTo :: CGid -> CGid -> [CGid] Source # enumFromThenTo :: CGid -> CGid -> CGid -> [CGid] Source #
Ix CGid |
Instance details Defined in System.Posix.Types Methods range :: (CGid, CGid) -> [CGid] Source # index :: (CGid, CGid) -> CGid -> Int Source # unsafeIndex :: (CGid, CGid) -> CGid -> Int Source # inRange :: (CGid, CGid) -> CGid -> Bool Source # rangeSize :: (CGid, CGid) -> Int Source # unsafeRangeSize :: (CGid, CGid) -> Int Source #
Num CGid |
Instance details Defined in System.Posix.Types Methods (+) :: CGid -> CGid -> CGid Source # (-) :: CGid -> CGid -> CGid Source # (*) :: CGid -> CGid -> CGid Source # negate :: CGid -> CGid Source # abs :: CGid -> CGid Source # signum :: CGid -> CGid Source # fromInteger :: Integer -> CGid Source #
Read CGid |
Instance details Defined in System.Posix.Types Methods readsPrec :: Int -> ReadS CGid Source # readList :: ReadS [CGid] Source # readPrec :: ReadPrec CGid Source # readListPrec :: ReadPrec [CGid] Source #
Integral CGid |
Instance details Defined in System.Posix.Types Methods quot :: CGid -> CGid -> CGid Source # rem :: CGid -> CGid -> CGid Source # div :: CGid -> CGid -> CGid Source # mod :: CGid -> CGid -> CGid Source # quotRem :: CGid -> CGid -> (CGid, CGid) Source # divMod :: CGid -> CGid -> (CGid, CGid) Source # toInteger :: CGid -> Integer Source #
Real CGid |
Instance details Defined in System.Posix.Types Methods toRational :: CGid -> Rational Source #
Show CGid |
Instance details Defined in System.Posix.Types Methods showsPrec :: Int -> CGid -> ShowS Source # show :: CGid -> String Source # showList :: [CGid] -> ShowS Source #
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 #

type GroupID = CGid Source #

type UserID = CUid Source #

modifyProcessHandle :: ProcessHandle -> (ProcessHandle__ -> IO (ProcessHandle__, a)) -> IO a Source #

withProcessHandle :: ProcessHandle -> (ProcessHandle__ -> IO a) -> IO a Source #

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.

- 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. See $exec-on-windows for details.

  Default: `False`

  Since: process-1.5.0.0

#### Instances

Instances details

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

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

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 Methods fromString :: String -> CmdSpec Source #
Show CmdSpec Source # |
Instance details Defined in System.Process.Common Methods showsPrec :: Int -> CmdSpec -> ShowS Source # show :: CmdSpec -> String Source # showList :: [CmdSpec] -> ShowS Source #
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 `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

Instances details

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

data ProcRetHandles Source #

contains the handles returned by a call to createProcess_Internal

Constructors

ProcRetHandles |

Fields

- hStdInput :: Maybe Handle
- hStdOutput :: Maybe Handle
- hStdError :: Maybe Handle
- procHandle :: ProcessHandle

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:

- `Handle`s 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.

startDelegateControlC :: IO () Source #

endDelegateControlC :: ExitCode -> IO () Source #

stopDelegateControlC :: IO () Source #

unwrapHandles :: ProcRetHandles -> (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) Source #

pPrPr_disableITimers :: IO () Source #

c_execvpe :: CString -> Ptr CString -> Ptr CString -> IO CInt Source #

ignoreSignal :: CLong Source #

defaultSignal :: CLong Source #

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

withFilePathException :: FilePath -> IO a -> IO a Source #

withCEnvironment :: [(String, String)] -> (Ptr CString -> IO a) -> IO a Source #

translate :: String -> String Source #

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